@cursor/july 0.1.45 → 0.1.47

package/dist/internal/ledger-serving.js

@@ -1,24 +1,35 @@
 /**
- * Ledger-mode serving seam (`serving: "ledger"` on `defineAgent`):
- * coordination only, no inbox. Every engine `send` acquires the session
- * lease before its turn runs and commits (head+1, lease released) after
- * it completes, so cross-pod mutual exclusion, generation fencing, and
- * the committed head sequence are real.
+ * Ledger-mode serving seam (`serving: "ledger"` on `defineAgent`): an event
+ * pump that routes every engine `send` through the KV session ledger
+ * instead of starting turns directly.
  *
- * **Durability trade-off (deliberate):** there is no durable mailbox.
- * An event that arrives while the lease is held does NOT park in the
- * store — the delivering pod waits *in-process*: local concurrent sends
- * serialize on a per-session promise chain (no claim spinning), and a
- * lease held by another pod is waited out with bounded claim retries. A
- * crash therefore loses the in-flight event exactly as resident serving
- * does. A dead pod's lease simply expires (~30s TTL); the next delivery
- * claims at generation+1 — no janitor is needed because nothing is
- * parked.
+ * Delivery: ensureSession (continuation key, as today) → principal gate
+ * (an existing session rejects a sender that is not its principal BEFORE
+ * anything is parked; mirrors the resident `samePrincipal` check) →
+ * appendEvent (payload + CAS — the source ack point moves after this) →
+ * claim → drain → run the drained turns through the resident engine path →
+ * commit (heartbeats while turns run) → repeat while the commit reports
+ * pending. A deliver that finds the lease held walks away (the holder's
+ * commit sees the append); the janitor recovers sessions whose holder
+ * died. A foreign-principal envelope that reaches the mailbox anyway is
+ * consumed and committed away at drain (warn log), never replayed.
  *
- * Re-entrancy caveat (same shape as resident `waitForCompletion`): a
- * send issued from *inside* a running turn against the same session
- * chains behind that turn's serve, so awaiting its resolution from the
- * turn would deadlock. Fire-and-forget such sends.
+ * v1 scope: the mailbox envelope carries `message`, `auth`, `title`,
+ * `state`, `mode`, `purpose`, and the isolation-relevant per-send
+ * overrides `workspaceDir` and `cloud` — the two options
+ * `resolveSessionRuntime` and harness-cwd selection read. Dropping
+ * those is a sandbox escape, not a feature gap: without them a drained
+ * GitHub/Slack turn falls back to the local runtime with the default
+ * harness cwd, so untrusted channel content drives tools on the serve
+ * host instead of the cloud VM / channel worktree. `coalesceSourceTs`
+ * (when present) is used as the drain-ordering `sourceTs`. Deferred
+ * (documented, not silently faked — deliver logs a warning naming what
+ * it dropped): `workspaceFiles` and per-turn `images` (content
+ * injection, and their base64 payloads can blow the mailbox blob past
+ * hosted KV value caps), `sdkAgentId` seeding, and `admission`
+ * semantics (both `"preempt"` and Slack `"coalesce"` nudge bookkeeping
+ * — ledger draining already serializes turns, but nothing is
+ * interrupted or coalesced through the mailbox).
  */
 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,77 +41,277 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { randomBytes, randomUUID } from "node:crypto";
-import { HEARTBEAT_INTERVAL_MS, LEASE_TTL_MS, LedgerFencedError, } from "../ledger/session-ledger.js";
+import { createLedgerJanitor } from "../ledger/janitor.js";
+import { HEARTBEAT_INTERVAL_MS, LedgerFencedError, } from "../ledger/session-ledger.js";
+import { SessionAuthError, samePrincipal } from "./auth.js";
+import { describeError } from "./describe-error.js";
 import { newContinuationKey } from "./ids.js";
-/** Wait between claim retries while another holder has the lease. */
-export const CLAIM_RETRY_DELAY_MS = 250;
-/**
- * Give up waiting for the lease after this long — two full lease TTLs,
- * so a dead holder's expiry (~30s) is always survived with margin.
- */
-export const CLAIM_WAIT_TIMEOUT_MS = 2 * LEASE_TTL_MS;
 export class LedgerServing {
     constructor(options) {
-        var _a, _b, _c, _d, _e, _f;
-        /**
-         * Per-ledger-session in-process serialization: local concurrent sends
-         * queue here instead of spinning claim retries against our own lease.
-         */
-        this.chains = new Map();
+        var _a, _b, _c;
+        /** One pump per ledger session — the in-process face of the lease. */
+        this.pumps = new Map();
+        /** Fire-and-forget re-pump checks, awaited on close. */
+        this.background = new Set();
         this.ledger = options.ledger;
         this.deliverTurn = options.deliverTurn;
+        this.findSession = options.findSession;
         this.logger = (_a = options.logger) !== null && _a !== void 0 ? _a : (() => { });
         this.heartbeatIntervalMs = (_b = options.heartbeatIntervalMs) !== null && _b !== void 0 ? _b : HEARTBEAT_INTERVAL_MS;
-        this.claimRetryDelayMs = (_c = options.claimRetryDelayMs) !== null && _c !== void 0 ? _c : CLAIM_RETRY_DELAY_MS;
-        this.claimWaitTimeoutMs = (_d = options.claimWaitTimeoutMs) !== null && _d !== void 0 ? _d : CLAIM_WAIT_TIMEOUT_MS;
-        this.clock = (_e = options.clock) !== null && _e !== void 0 ? _e : Date.now;
-        this.sleep = (_f = options.sleep) !== null && _f !== void 0 ? _f : ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.clock = (_c = options.clock) !== null && _c !== void 0 ? _c : Date.now;
+        this.janitor = createLedgerJanitor(Object.assign(Object.assign({ ledger: options.ledger, onSession: (claimed) => this.serveClaimed(claimed), 
+            // Consumed mailbox blobs (full message envelopes) would otherwise
+            // accumulate forever; the default TTL (1h) is far beyond any lease
+            // or turn horizon, so only truly dead blobs are collected.
+            orphanSweep: {} }, (options.janitorIntervalMs === undefined
+            ? {}
+            : { intervalMs: options.janitorIntervalMs })), { onError: (error, sessionId) => {
+                this.logger(`[ledger] janitor error${sessionId === undefined ? "" : ` (session ${sessionId})`}: ${describeError(error)}`);
+            }, clock: this.clock }));
     }
-    /** Settle every queued and in-flight delivery. */
+    /** Start the janitor loop (recovers expired-lease sessions). */
+    start() {
+        this.janitor.start();
+    }
+    /** Stop the janitor and settle in-flight pumps and re-pump checks. */
     close() {
         return __awaiter(this, void 0, void 0, function* () {
-            yield Promise.allSettled([...this.chains.values()]);
+            // Awaiting stop() matters: an in-flight janitor pass can claim a
+            // session and register a pump after this method snapshots the maps.
+            yield this.janitor.stop();
+            yield Promise.allSettled([...this.pumps.values()]);
+            yield Promise.allSettled([...this.background]);
         });
     }
     /**
-     * Ledger-mode `send`: resolve the session identity, wait for the
-     * lease (in-process queue first, then cross-pod claim retries), run
-     * the turn, commit. Resolves with the engine session handle after the
-     * commit released the lease.
+     * Ledger-mode `send`: append the message to the session mailbox, then
+     * serve pending events (or walk away if another holder is already
+     * serving them). Resolves with the engine session handle once one
+     * exists — the ack point is the durable append, not turn completion —
+     * so HTTP create/follow-up can return a session id while the holder is
+     * still in flight. When this process wins the claim, the pump keeps
+     * draining in the background; callers that need the turn to finish use
+     * `waitForCompletion` (and the lease releases on the pump's commit).
+     * When another holder is serving the session and no engine session
+     * exists on this pod, the delivery is still a success — the event is
+     * durably parked and the holder's commit (or the janitor) drains it —
+     * so the resolved handle is a parked stand-in carrying the durable
+     * session identity.
      */
     deliver(channelId, message, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
+            var _a, _b, _c;
             const continuationToken = (_a = options.continuationToken) !== null && _a !== void 0 ? _a : newContinuationKey();
+            this.warnOnDroppedOptions(channelId, options);
             const ensured = yield this.ledger.ensureSession(`${channelId}/${continuationToken}`);
-            return this.enqueue(ensured.session.sessionId, () => this.serveOne(ensured.session.sessionId, {
+            const ledgerSessionId = ensured.session.sessionId;
+            // Principal gate BEFORE the durable append: once an envelope is
+            // parked it WILL be drained, so a foreign sender must be rejected
+            // here — not on the resident path after the mailbox write. A new
+            // ledger session has no owner yet: the creating sender becomes it,
+            // exactly as on resident session creation.
+            if (!ensured.created) {
+                const existing = yield this.findSession(channelId, continuationToken);
+                if (existing !== undefined) {
+                    if (!samePrincipal(existing.info.auth, (_b = options.auth) !== null && _b !== void 0 ? _b : null)) {
+                        throw new SessionAuthError(existing.id);
+                    }
+                }
+                // No handle: the engine session does not exist yet (the first
+                // parked event has not run — the lease holder creates it) or a
+                // cross-pod restore transiently failed. Park rather than fail
+                // closed: rejecting here would bounce the legitimate owner racing
+                // the session's first turn. This is not fail-open — the resident
+                // path re-checks the principal when the event drains, and the
+                // drain treats a SessionAuthError as consume-and-commit, so a
+                // foreign envelope that parks through this window costs one warn
+                // line and never actuates, bricks, or replays the session.
+            }
+            const envelope = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ channelId,
+                continuationToken,
+                message, auth: (_c = options.auth) !== null && _c !== void 0 ? _c : null }, (options.title === undefined ? {} : { title: options.title })), (options.state === undefined ? {} : { state: options.state })), (options.mode === undefined ? {} : { mode: options.mode })), (options.purpose === undefined ? {} : { purpose: options.purpose })), (options.workspaceDir === undefined
+                ? {}
+                : { workspaceDir: options.workspaceDir })), (options.cloud === undefined ? {} : { cloud: options.cloud }));
+            yield this.ledger.appendEvent(ledgerSessionId, {
+                eventId: `evt_${randomBytes(12).toString("hex")}`,
+                envelope: envelope,
+                sourceTs: this.resolveSourceTs(options),
+            });
+            // Ack point: the event is durable (mailbox blob + ledger pending).
+            // Do not await the pump: awaiting turns here would block HTTP create
+            // until the first turn committed, so a client could never park a
+            // mid-turn follow-up and a second pod would see a released lease.
+            const serving = this.servePending(ledgerSessionId);
+            return this.resolveDeliverHandle({
                 channelId,
                 continuationToken,
-                message,
-                options,
-            }));
+                ledgerSessionId,
+                envelope,
+                created: ensured.created,
+                serving,
+            });
         });
     }
-    /** Chain a delivery behind the session's in-flight ones. */
-    enqueue(ledgerSessionId, run) {
+    /**
+     * The stand-in handle for a delivery whose event is parked while
+     * another holder serves the session: real durable identity, no local
+     * turn. `waitForCompletion` resolves immediately — the parked event's
+     * turn runs on the holder, so there is nothing local to await (the
+     * same contract as a coalesced send, whose outcome is not its own
+     * message's turn). The event stream and re-keying live wherever the
+     * turn runs, so both fail loudly here.
+     */
+    parkedSession(ledgerSessionId, envelope, isNew) {
         var _a;
-        const prior = (_a = this.chains.get(ledgerSessionId)) !== null && _a !== void 0 ? _a : Promise.resolve();
-        const next = prior.then(() => run(), () => run());
-        this.chains.set(ledgerSessionId, next);
-        void next
-            .catch(() => { })
-            .finally(() => {
-            if (this.chains.get(ledgerSessionId) === next) {
-                this.chains.delete(ledgerSessionId);
+        const unavailable = (what) => new Error(`ledger serving: ${what} is unavailable for session ${ledgerSessionId}: the parked event runs on the session's current lease holder, not this process`);
+        return {
+            id: ledgerSessionId,
+            continuationToken: envelope.continuationToken,
+            isNew,
+            info: Object.assign(Object.assign(Object.assign({ id: ledgerSessionId, channelId: envelope.channelId, mode: (_a = envelope.mode) !== null && _a !== void 0 ? _a : "chat", auth: envelope.auth }, (envelope.title === undefined ? {} : { title: envelope.title })), (envelope.purpose === undefined
+                ? {}
+                : { purpose: envelope.purpose })), { continuationKey: envelope.continuationToken }),
+            getEventStream: () => Promise.reject(unavailable("the event stream")),
+            waitForCompletion: () => __awaiter(this, void 0, void 0, function* () { return ({ status: "finished" }); }),
+            setContinuationToken: () => Promise.reject(unavailable("re-keying the continuation token")),
+        };
+    }
+    /**
+     * Return a handle as soon as the engine session exists, without waiting
+     * for the pump to commit. If the pump settles without creating a
+     * session (walk-away, or a throw before admit), surface that: rethrow
+     * a failed claimant turn, otherwise the parked stand-in.
+     */
+    resolveDeliverHandle(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { channelId, continuationToken, ledgerSessionId, envelope, created, serving, } = args;
+            for (;;) {
+                const handle = yield this.findSession(channelId, continuationToken);
+                if (handle !== undefined) {
+                    return handle;
+                }
+                const pump = this.pumps.get(ledgerSessionId);
+                if (pump !== undefined) {
+                    yield Promise.race([
+                        new Promise((resolve) => {
+                            setTimeout(resolve, 15);
+                        }),
+                        pump.then(() => undefined, () => undefined),
+                    ]);
+                    continue;
+                }
+                const createdLate = yield this.findSession(channelId, continuationToken);
+                if (createdLate !== undefined) {
+                    return createdLate;
+                }
+                yield serving;
+                this.logger(`[ledger] deliver on channel "${channelId}": event parked for session ${ledgerSessionId} (continuation ${continuationToken}); another holder is serving it and no local session exists — its commit (or the janitor) drains the event`);
+                return this.parkedSession(ledgerSessionId, envelope, created);
+            }
+        });
+    }
+    /**
+     * Drain ordering: prefer the real source time over this pod's receipt
+     * time. `coalesceSourceTs` is a Slack-style seconds string
+     * (`"1712345678.000100"`); normalize sub-epoch-ms values to ms so they
+     * stay comparable with the `Date.now()` fallback.
+     */
+    resolveSourceTs(options) {
+        if (options.coalesceSourceTs !== undefined) {
+            const parsed = Number(options.coalesceSourceTs);
+            if (Number.isFinite(parsed) && parsed > 0) {
+                return parsed < 1e11 ? Math.round(parsed * 1000) : parsed;
+            }
+        }
+        return this.clock();
+    }
+    /**
+     * One warning per delivery naming the send options the mailbox does not
+     * replay — better a loud line than an author silently losing images or
+     * admission semantics on a ledger-mode agent.
+     */
+    warnOnDroppedOptions(channelId, options) {
+        const dropped = ["images", "sdkAgentId", "admission", "workspaceFiles"].filter((name) => options[name] !== undefined);
+        if (dropped.length > 0) {
+            this.logger(`[ledger] deliver on channel "${channelId}": dropping send options not replayed through the mailbox: ${dropped.join(", ")}`);
+        }
+    }
+    /**
+     * Serve a session's pending events. When a pump is already running the
+     * caller walks away (the holder's commit re-reads pending) — except
+     * that the holder's *final* commit may have released before this
+     * append landed, so a re-check is chained behind it. Deliver never
+     * awaits this promise for its full lifetime: awaiting a new pump would
+     * block HTTP until the turn committed, and awaiting a running pump
+     * would deadlock a send issued from inside one of its turns.
+     */
+    servePending(ledgerSessionId) {
+        const running = this.pumps.get(ledgerSessionId);
+        if (running !== undefined) {
+            const recheck = running
+                .catch(() => { })
+                .then(() => this.repumpIfPending(ledgerSessionId))
+                .catch(() => { });
+            this.background.add(recheck);
+            void recheck.finally(() => {
+                this.background.delete(recheck);
+            });
+            return Promise.resolve();
+        }
+        return this.track(ledgerSessionId, () => this.runPump(ledgerSessionId));
+    }
+    /** Claim-or-defer entry used after an append and after a pump settles. */
+    runPump(ledgerSessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const claim = yield this.ledger.claim(ledgerSessionId);
+            if (!claim.claimed) {
+                return;
+            }
+            yield this.runClaimedTurns(ledgerSessionId, claim.lease);
+        });
+    }
+    /** Janitor hand-off: the claim already happened, just run the turns. */
+    serveClaimed(claimed) {
+        return this.track(claimed.sessionId, () => this.runClaimedTurns(claimed.sessionId, claimed.lease));
+    }
+    /**
+     * Re-pump after the previous holder settled, covering the release window
+     * where an append landed after that holder's final commit.
+     */
+    repumpIfPending(ledgerSessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.pumps.has(ledgerSessionId)) {
+                return;
+            }
+            const snapshot = yield this.ledger.readLedger(ledgerSessionId);
+            if (snapshot === undefined || snapshot.pending.length === 0) {
+                return;
+            }
+            if (snapshot.lease !== null && snapshot.lease.expiresAt > this.clock()) {
+                return;
+            }
+            yield this.track(ledgerSessionId, () => this.runPump(ledgerSessionId));
+        });
+    }
+    /** Register a pump in the per-session map for its lifetime. */
+    track(ledgerSessionId, run) {
+        const tracked = run().finally(() => {
+            if (this.pumps.get(ledgerSessionId) === tracked) {
+                this.pumps.delete(ledgerSessionId);
             }
         });
-        return next;
+        this.pumps.set(ledgerSessionId, tracked);
+        return tracked;
     }
-    /** claim (waiting) → resident turn → commit-release. */
-    serveOne(ledgerSessionId, request) {
+    /**
+     * The drain → turn → commit loop for a held lease. Heartbeats extend the
+     * lease while turns run; a fenced heartbeat (or fenced commit) means a
+     * new holder took over — discard without committing; the new holder
+     * re-drains (at-least-once actuation, exactly-once ledger apply).
+     */
+    runClaimedTurns(ledgerSessionId, lease) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
-            const lease = yield this.claimWithWait(ledgerSessionId);
             let fenced = false;
             const heartbeat = setInterval(() => {
                 this.ledger.heartbeat(ledgerSessionId, lease.generation).then((result) => {
@@ -113,60 +324,68 @@ export class LedgerServing {
             }, this.heartbeatIntervalMs);
             (_a = heartbeat.unref) === null || _a === void 0 ? void 0 : _a.call(heartbeat);
             try {
-                let handle;
-                try {
-                    handle = yield this.deliverTurn(request);
-                    yield handle.waitForCompletion();
-                }
-                catch (error) {
-                    // The turn never committed; free the session for the next
-                    // delivery instead of making it wait out the TTL. A fenced
-                    // holder's release is a no-op.
-                    yield this.ledger
-                        .release(ledgerSessionId, lease.generation)
-                        .catch(() => { });
-                    throw error;
+                for (;;) {
+                    if (fenced) {
+                        return;
+                    }
+                    const { head, events } = yield this.ledger.drain(ledgerSessionId);
+                    if (events.length === 0) {
+                        yield this.ledger.release(ledgerSessionId, lease.generation);
+                        return;
+                    }
+                    for (const event of events) {
+                        if (fenced) {
+                            return;
+                        }
+                        const envelope = event.envelope;
+                        try {
+                            const session = yield this.deliverTurn(envelope);
+                            yield session.waitForCompletion();
+                        }
+                        catch (error) {
+                            if (!(error instanceof SessionAuthError)) {
+                                throw error;
+                            }
+                            // Defense in depth behind deliver's principal gate: a parked
+                            // envelope from a foreign principal (gate raced the session's
+                            // first turn, or a pre-gate build wrote it) is consumed and
+                            // committed away like any drained event. Aborting the batch
+                            // instead would replay the already-actuated turns before it
+                            // and re-throw on every future drain — one poison event must
+                            // cost a log line, never a stuck session.
+                            this.logger(`[ledger] session ${ledgerSessionId}: discarding parked event ${event.eventId} — its sender is not the session's principal (${describeError(error)})`);
+                        }
+                    }
+                    const commit = yield this.ledger.commit(ledgerSessionId, {
+                        drainedEventIds: events.map((event) => event.eventId),
+                        generation: lease.generation,
+                        expectedHead: head,
+                        commitId: randomUUID(),
+                    });
+                    if (commit.leaseReleased) {
+                        return;
+                    }
                 }
-                if (fenced) {
-                    // A new holder took over mid-turn (our lease lapsed). Discard:
-                    // committing would fence anyway, and warm state is now stale.
-                    this.logger(`[ledger] session ${ledgerSessionId} fenced mid-turn (generation ${lease.generation}); discarding without commit`);
-                    throw new LedgerFencedError(`deliver(${ledgerSessionId}): fenced mid-turn at generation ${lease.generation}`);
+            }
+            catch (error) {
+                if (error instanceof LedgerFencedError) {
+                    this.logger(`[ledger] session ${ledgerSessionId} fenced mid-turn (generation ${lease.generation}); discarding — the new holder re-drains`);
+                    return;
                 }
-                yield this.ledger.commit(ledgerSessionId, {
-                    generation: lease.generation,
-                    expectedHead: lease.head,
-                    commitId: randomUUID(),
-                });
-                return handle;
+                // The turn never committed; free the session for the next
+                // append-driven claim instead of making it wait out the lease TTL
+                // (and the janitor cadence). Best-effort: a fenced holder's
+                // release is a no-op, and the events stay pending either way.
+                yield this.ledger
+                    .release(ledgerSessionId, lease.generation)
+                    .catch(() => { });
+                throw error;
             }
             finally {
                 clearInterval(heartbeat);
             }
         });
     }
-    /**
-     * Claim the lease, waiting out another holder with bounded retries.
-     * The common waits are short: our own pod's deliveries never reach
-     * here concurrently (the in-process chain serializes them), so a held
-     * lease means another pod is serving — usually for one turn — or died
-     * (expiry unblocks us at ~30s).
-     */
-    claimWithWait(ledgerSessionId) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const start = this.clock();
-            for (;;) {
-                const claim = yield this.ledger.claim(ledgerSessionId);
-                if (claim.claimed) {
-                    return { generation: claim.lease.generation, head: claim.head };
-                }
-                if (this.clock() - start >= this.claimWaitTimeoutMs) {
-                    throw new Error(`ledger serving: session ${ledgerSessionId} is still leased by ${claim.holder} after ${this.claimWaitTimeoutMs}ms; giving up on this delivery`);
-                }
-                yield this.sleep(this.claimRetryDelayMs);
-            }
-        });
-    }
 }
 /** Mint the lease holder id for this process. */
 export function newLedgerPodId() {

package/dist/internal/sdk-runner.d.ts

@@ -32,6 +32,22 @@ export type PrewarmOutcome = {
     readonly warmed: false;
     readonly reason: string;
 };
+/**
+ * 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 declare const SERVE_WORKSPACE_SCAN_CACHE_TTL_MS: number;
+/**
+ * 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 declare function resolveServeWorkspaceScanCacheTtlMs(args: {
+    dev: boolean;
+    env?: NodeJS.ProcessEnv;
+}): number | undefined;
 export interface CursorSdkRunnerOptions {
     /** Cursor API key. Defaults to the `CURSOR_API_KEY` environment variable. */
     apiKey?: string;
@@ -43,6 +59,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;
 }
 /**
  * The backend's `NotLoggedIn` copy ("Authentication error" title, "try

package/dist/internal/sdk-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk-runner.d.ts","sourceRoot":"","sources":["../../src/internal/sdk-runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,SAAS,EAEf,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,KAAK,YAAY,EAEjB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAEjB,MAAM,aAAa,CAAC;AAGrB,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1D;;;;;OAKG;IACH,OAAO,CAAC,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACjE,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CACrC,iBAAiB,EACf,cAAc,GACd,gBAAgB,GAChB,SAAS,GACT,OAAO,GACP,YAAY,GACZ,WAAW,GACX,OAAO,CACV,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAcxD,MAAM,WAAW,sBAAsB;IACrC,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAwBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAKvE;AAED,qBAAa,eAAgB,YAAW,WAAW;IAKrC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+C;IACtE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkC;IAElE,YAA6B,OAAO,GAAE,sBAA2B,EAAI;IAE/D,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAkC9D;YAEa,cAAc;IA6F5B;;;;OAIG;IACG,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAepE;IAEK,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAY7B;IAED,OAAO,CAAC,QAAQ;IA0BhB;;;;OAIG;IACH,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,kBAAkB;IAc1B;;;OAGG;YACW,iBAAiB;YAuBjB,SAAS;YAOT,cAAc;YA6Bd,cAAc;IA6C5B,OAAO,CAAC,QAAQ;CAUjB;AAED,4EAA4E;AAC5E,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAMT;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,cAAc,CAQpE;AAwGD,wBAAgB,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,MAAM,CAExE"}
+{"version":3,"file":"sdk-runner.d.ts","sourceRoot":"","sources":["../../src/internal/sdk-runner.ts"],"names":[],"mappings":"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"}

package/dist/internal/sdk-runner.js

@@ -15,9 +15,36 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { mkdir } from "node:fs/promises";
-import { Agent, createAgentPlatform, JsonlLocalAgentStore, } from "@cursor/sdk";
+import { Agent, Cursor, createAgentPlatform, JsonlLocalAgentStore, } from "@cursor/sdk";
 import { DEFAULT_MODEL, } from "../types.js";
 import { mapSdkTokenUsage, usageTokenSum } from "./cloud-turn-cost.js";
+/**
+ * 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 = 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) {
+    var _a;
+    var _b;
+    const raw = (_a = ((_b = args.env) !== null && _b !== void 0 ? _b : process.env).CURSOR_RIPWALK_CACHE_TTL_MS) === null || _a === void 0 ? void 0 : _a.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;
+}
 /**
  * How long one SDK agent handle (and the Connect transport inside it) may be
  * reused before the runner retires it.
@@ -52,6 +79,12 @@ export class CursorSdkRunner {
         this.agents = new Map();
         this.stores = new Map();
         this.prewarmReleases = [];
+        if (options.workspaceScanCacheTtlMs !== undefined) {
+            Cursor.configure({
+                local: { workspaceScanCacheTtlMs: options.workspaceScanCacheTtlMs },
+            });
+            this.log(`[agent-sdk] workspace scan cache ttl=${options.workspaceScanCacheTtlMs}ms`);
+        }
     }
     runTurn(request) {
         return __awaiter(this, void 0, void 0, function* () {

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

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/internal/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4BH,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAOhB,YAAY,EACb,MAAM,aAAa,CAAC;AAyGrB,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,iBAAiB,CAAC;AAiBpE,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;CACvB;AAaD,6EAA6E;AAC7E,MAAM,WAAW,0BAA0B;IACzC,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,GAAE,YAAY,GAAG,0BAA+B,GACtD,OAAO,CAAC,gBAAgB,CAAC,CAkvB3B"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/internal/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6BH,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAOhB,YAAY,EACb,MAAM,aAAa,CAAC;AAyGrB,OAAO,EACL,KAAK,WAAW,EAGjB,MAAM,iBAAiB,CAAC;AAiBzB,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;CACvB;AAaD,6EAA6E;AAC7E,MAAM,WAAW,0BAA0B;IACzC,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,GAAE,YAAY,GAAG,0BAA+B,GACtD,OAAO,CAAC,gBAAgB,CAAC,CAwvB3B"}

package/dist/internal/server.js

@@ -35,7 +35,7 @@ import { Buffer } from "node:buffer";
 import { once } from "node:events";
 import { createServer, } from "node:http";
 import { join } from "node:path";
-import { createCursorAccountGithubTokenResolver, getGithubCursorAccountRuntime, parseCursorGithubRepoScope, resolveCursorGithubPermissions, resolveCursorGithubProxyUrl, } from "../channels/github/cursor-account.js";
+import { createCursorAccountGithubTokenResolver, cursorGithubPermissionsForChannel, getGithubCursorAccountRuntime, parseCursorGithubRepoScope, resolveCursorGithubPermissions, resolveCursorGithubProxyUrl, } from "../channels/github/cursor-account.js";
 import { findGitHubChannelTargets } from "../channels/github/forward.js";
 import { dispatchCursorSlackEnvelope, getSlackCursorAccountRuntime, } from "../channels/slack/cursor-account.js";
 import { assertSlackCursorAgentName } from "../channels/slack/types.js";
@@ -72,7 +72,7 @@ import { ReminderRunner, ReminderValidationError, UnknownReminderError, } from "
 import { assertAccountConnectionsNotAnonymous, resolveMountConnections, validateMountConnectionsConfig, } from "./resolved-connections.js";
 import { Router } from "./router.js";
 import { ScheduleRunner, UnknownScheduleError } from "./schedule-runner.js";
-import { CursorSdkRunner } from "./sdk-runner.js";
+import { CursorSdkRunner, resolveServeWorkspaceScanCacheTtlMs, } from "./sdk-runner.js";
 import { SessionAuthError, SessionBusyError, SessionEngine, ToolInputError, ToolNotDirectlyCallableError, UnknownToolError, } from "./session-engine.js";
 import { sessionUrlsForRequest } from "./session-urls.js";
 const MAX_BODY_BYTES = 32 * 1024 * 1024;
@@ -212,7 +212,12 @@ export function startServer(mounts_1) {
         if (options.allowAnonymous === true) {
             logger("[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 runner = (_l = options.runner) !== null && _l !== void 0 ? _l : new CursorSdkRunner(Object.assign(Object.assign({}, (accountKey === undefined ? {} : { apiKey: accountKey.apiKey })), { logger }));
+        const workspaceScanCacheTtlMs = resolveServeWorkspaceScanCacheTtlMs({
+            dev,
+        });
+        const runner = (_l = options.runner) !== null && _l !== void 0 ? _l : new CursorSdkRunner(Object.assign(Object.assign(Object.assign({}, (accountKey === undefined ? {} : { apiKey: accountKey.apiKey })), { logger }), (workspaceScanCacheTtlMs === undefined
+            ? {}
+            : { workspaceScanCacheTtlMs })));
         const router = new Router();
         const runtimes = [];
         const channelStopHooks = [];
@@ -1450,7 +1455,7 @@ function resolveCursorGithubEventConfig(input) {
             ...((_b = (_a = target.accountRuntime.scope) === null || _a === void 0 ? void 0 : _a.repos) !== null && _b !== void 0 ? _b : []),
         ]; }),
     ];
-    const permissions = resolveCursorGithubPermissions(input.targets.map((target) => { var _a; var _b; return (_b = (_a = target.accountRuntime.scope) === null || _a === void 0 ? void 0 : _a.permissions) !== null && _b !== void 0 ? _b : "pr-write"; }));
+    const permissions = resolveCursorGithubPermissions(input.targets.map((target) => { var _a; return cursorGithubPermissionsForChannel(target.accountRuntime.options, (_a = target.accountRuntime.scope) === null || _a === void 0 ? void 0 : _a.permissions); }));
     const scope = parseCursorGithubRepoScope(repos, permissions);
     return {
         cursorEvents: Object.assign(Object.assign({}, input.configured), { repos: [...scope.repos] }),