@cursor/july 0.1.114 → 0.2.0

package/dist/internal/reminder-runner.js

@@ -20,7 +20,7 @@ import { parseDuration } from "./duration.js";
 import { REMINDER_CP_PROTOCOL_VERSION, scheduleSpecFromCreateInput, toWireReschedule, } from "./reminder-control-plane-protocol.js";
 import { defaultBusyPolicy, MAX_TIMER_MS, nextCronFireMs, ReminderValidationError, resolveSchedule, } from "./reminder-schedule.js";
 import { APP_AUTH } from "./schedule-runner.js";
-import { HTTP_CHANNEL_ID, SessionBusyError, } from "./session-engine.js";
+import { HTTP_CHANNEL_ID, SessionAuthError, SessionBusyError, } from "./session-engine.js";
 export { ReminderValidationError } from "./reminder-schedule.js";
 /** Max UTF-8 byte length of `JSON.stringify(args)` on named-handler create. */
 export const REMINDER_ARGS_MAX_BYTES = 32 * 1024;
@@ -31,6 +31,13 @@ export class UnknownReminderError extends Error {
         this.name = "UnknownReminderError";
     }
 }
+/**
+ * Reschedule applied when a hosted fire cannot open a session (no
+ * principal). A one-shot `skipped` outcome without a reschedule completes
+ * the reminder, which would lose the check-in for good.
+ */
+export const REMINDER_SESSION_OPEN_RETRY_DELAY = "5m";
+export const REMINDER_FIRE_OUTCOME_METRIC = "agent_sdk.reminder.fire_outcome";
 /**
  * Server wiring for {@link ReminderRunnerOptions.rejectAnonymousHandlers}:
  * architecture v2 always rejects anonymous run/until (local or hosted).
@@ -95,6 +102,19 @@ function toInfo(record) {
         hasUntilFn: record.hasUntilFn === true,
     };
 }
+function stopFire(reason) {
+    return { outcome: { kind: "stop", reason }, reason };
+}
+function runReason(result) {
+    switch (result.action) {
+        case "stop":
+            return "run_stop";
+        case "skip":
+            return "run_skip";
+        case "delivered":
+            return "run_delivered";
+    }
+}
 function buildFirePrompt(record) {
     var _a;
     const recurring = record.scheduleKind === "every" || record.scheduleKind === "cron";
@@ -128,9 +148,15 @@ export class ReminderRunner {
         /** Single-flight idle gates keyed by `channelId:continuationToken`. */
         this.idleGates = new Map();
         this.started = false;
+        /**
+         * A control-plane read failure is logged once per outage, not per call.
+         * The next successful read re-arms the log.
+         */
+        this.controlPlaneReadFailureLogged = false;
         this.rejectAnonymousHandlers = options.rejectAnonymousHandlers === true;
         this.controlPlane = options.controlPlane;
         this.architecture = options.architecture;
+        this.hostedGuest = options.hostedGuest;
         for (const reminder of (_a = options.namedHandlers) !== null && _a !== void 0 ? _a : []) {
             this.namedHandlers.set(reminder.name, reminder.definition);
             this.namedHandlerNames.set(reminder.definition, reminder.name);
@@ -140,27 +166,56 @@ export class ReminderRunner {
     get usesControlPlaneProtocol() {
         return this.controlPlane !== undefined && this.architecture === "v2";
     }
+    /**
+     * Where reminder documents are read from. Under the CP protocol that is
+     * the v2 control-plane client; the v1 timed-work route answers 405 for a
+     * v2 deployment, which used to leave `list()` with only this process's
+     * in-memory map (breaking arm idempotence and `cancelForContinuation`).
+     */
+    get reminderReader() {
+        if (this.usesControlPlaneProtocol) {
+            return this.controlPlane;
+        }
+        return this.platformTimers;
+    }
+    logControlPlaneReadFailure(what, error) {
+        if (this.usesControlPlaneProtocol && this.controlPlaneReadFailureLogged) {
+            return;
+        }
+        this.controlPlaneReadFailureLogged = true;
+        this.logger(`[agent-sdk] reminders: control-plane ${what} failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
     /**
      * Load reminder documents from the control plane into memory. Does not
      * arm in-process timers — the CP owns clocks.
      */
     hydrate() {
         return __awaiter(this, void 0, void 0, function* () {
-            if (this.platformTimers === undefined) {
+            const reader = this.reminderReader;
+            if (reader === undefined) {
                 return;
             }
             let remote = [];
             try {
-                remote = yield this.platformTimers.listReminders();
+                remote = yield reader.listReminders();
             }
             catch (error) {
-                this.logger(`[agent-sdk] reminders: control-plane list failed: ${error instanceof Error ? error.message : String(error)}`);
+                this.logControlPlaneReadFailure("list", error);
                 return;
             }
+            this.controlPlaneReadFailureLogged = false;
             this.records.clear();
             for (const record of remote) {
                 this.records.set(record.id, record);
             }
+            if (this.usesControlPlaneProtocol) {
+                // The CP owns status; a fire whose handler is missing reports `stop`
+                // from executeFire instead of the guest writing a disarm.
+                if (remote.length > 0) {
+                    this.logger(`[agent-sdk] reminders: hydrated ${remote.length} reminder(s) from control plane`);
+                }
+                return;
+            }
             let disarmedOrphan = 0;
             for (const record of [...this.records.values()]) {
                 if (record.status !== "armed") {
@@ -238,9 +293,11 @@ export class ReminderRunner {
     }
     getRecord(id) {
         return __awaiter(this, void 0, void 0, function* () {
-            if (this.platformTimers !== undefined) {
+            const reader = this.reminderReader;
+            if (reader !== undefined) {
                 try {
-                    const remote = yield this.platformTimers.getReminder(id);
+                    const remote = yield reader.getReminder(id);
+                    this.controlPlaneReadFailureLogged = false;
                     if (remote === undefined) {
                         this.records.delete(id);
                         return undefined;
@@ -249,25 +306,35 @@ export class ReminderRunner {
                     return remote;
                 }
                 catch (error) {
-                    this.logger(`[agent-sdk] reminders: control-plane get failed for ${id}: ${error instanceof Error ? error.message : String(error)}`);
+                    this.logControlPlaneReadFailure(`get for ${id}`, error);
                     return this.records.get(id);
                 }
             }
             return this.records.get(id);
         });
     }
+    /**
+     * Under the CP protocol a list failure propagates: the in-memory map is
+     * only what this process created, and returning it would let a caller
+     * arm duplicates or miss rows to cancel. v1 keeps the best-effort form.
+     */
     allRecords() {
         return __awaiter(this, void 0, void 0, function* () {
-            if (this.platformTimers !== undefined) {
+            const reader = this.reminderReader;
+            if (reader !== undefined) {
                 try {
-                    const remote = yield this.platformTimers.listReminders();
+                    const remote = yield reader.listReminders();
+                    this.controlPlaneReadFailureLogged = false;
                     this.records.clear();
                     for (const record of remote) {
                         this.records.set(record.id, record);
                     }
                 }
                 catch (error) {
-                    this.logger(`[agent-sdk] reminders: control-plane list failed: ${error instanceof Error ? error.message : String(error)}`);
+                    this.logControlPlaneReadFailure("list", error);
+                    if (this.usesControlPlaneProtocol) {
+                        throw error;
+                    }
                 }
             }
             return [...this.records.values()];
@@ -533,25 +600,49 @@ export class ReminderRunner {
      */
     executeFire(descriptor) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
             const record = this.recordFromDescriptor(descriptor);
             this.records.set(record.id, record);
+            let fire;
+            try {
+                fire = yield this.runFire(record);
+            }
+            catch (error) {
+                // The hosted admission maps the throw to a retryable failure; count
+                // it so the retry loop is visible beside the settled outcomes.
+                this.recordFireOutcome(record, {
+                    kind: "error",
+                    reason: "fire_threw",
+                    detail: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
+            this.recordFireOutcome(record, {
+                kind: fire.outcome.kind,
+                reason: fire.reason,
+                turnStatus: fire.turnStatus,
+            });
+            return fire.outcome;
+        });
+    }
+    runFire(record) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
             const live = (_a = this.handlers.get(record.id)) !== null && _a !== void 0 ? _a : {};
             if (record.handler !== undefined) {
                 if (this.resolveNamedHandler(record.handler) === undefined) {
-                    return { kind: "stop", reason: "handler_missing" };
+                    return stopFire("handler_missing");
                 }
             }
             else if ((record.hasRunHandler === true || record.hasUntilFn === true) &&
                 live.run === undefined &&
                 live.untilFn === undefined) {
-                return { kind: "stop", reason: "handler_lost_on_restart" };
+                return stopFire("handler_lost_on_restart");
             }
             if (live.untilFn !== undefined) {
                 try {
                     const done = yield live.untilFn(this.buildUntilContext(record));
                     if (done) {
-                        return { kind: "stop", reason: "until_fn" };
+                        return stopFire("until_fn");
                     }
                 }
                 catch (error) {
@@ -560,47 +651,80 @@ export class ReminderRunner {
             }
             if (yield this.isSessionBusy(record.channelId, record.continuationToken)) {
                 if (record.busyPolicy === "skipIfBusy") {
-                    this.logger(`[agent-sdk] reminder "${record.id}" (${record.purpose}) skipped: session busy`);
-                    return { kind: "skipped" };
+                    return { outcome: { kind: "skipped" }, reason: "busy" };
                 }
                 yield this.whenSessionIdle(record.channelId, record.continuationToken);
             }
             let result;
+            let reason;
+            let turnStatus;
             if (record.handler !== undefined) {
                 const named = this.resolveNamedHandler(record.handler);
                 if (named === undefined) {
-                    return { kind: "stop", reason: "handler_missing" };
+                    return stopFire("handler_missing");
                 }
                 result = yield named.run(this.buildFireContext(record));
+                reason = runReason(result);
             }
             else if (live.run !== undefined) {
                 result = yield live.run(this.buildFireContext(record));
+                reason = runReason(result);
             }
             else if (record.prompt !== undefined) {
-                result = yield this.deliverPrompt(record);
+                const delivery = yield this.deliverPromptFire(record);
+                result = delivery.result;
+                reason = delivery.reason;
+                turnStatus = delivery.turnStatus;
             }
             else {
-                return { kind: "stop", reason: "missing_handler" };
+                return stopFire("missing_handler");
             }
             if (result.action === "stop") {
-                return { kind: "stop", reason: "run_stop" };
-            }
-            if (result.action === "skip") {
-                return {
-                    kind: "skipped",
-                    reschedule: result.reschedule !== undefined
-                        ? toWireReschedule(result.reschedule)
-                        : undefined,
-                };
+                return { outcome: { kind: "stop", reason }, reason };
             }
+            const reschedule = result.reschedule !== undefined
+                ? toWireReschedule(result.reschedule)
+                : undefined;
             return {
-                kind: "delivered",
-                reschedule: result.reschedule !== undefined
-                    ? toWireReschedule(result.reschedule)
-                    : undefined,
+                outcome: {
+                    kind: result.action === "skip" ? "skipped" : "delivered",
+                    reschedule,
+                },
+                reason,
+                turnStatus,
             };
         });
     }
+    /**
+     * One structured line and one `agent_sdk.reminder.fire_outcome` count per
+     * fire. Emitted through the host OTel meter, the same path hosted v2
+     * exports turn/tool metrics on, so a fire that ends in `stop` is visible
+     * beside the control plane's `timed_work.fire` count.
+     */
+    recordFireOutcome(record, fire) {
+        this.logger(`[agent-sdk] reminder fire_outcome kind=${fire.kind} reason=${fire.reason}` +
+            ` reminderId=${record.id} purpose=${record.purpose}` +
+            ` channelId=${record.channelId} fireCount=${record.fireCount}` +
+            (fire.turnStatus === undefined ? "" : ` turn=${fire.turnStatus}`) +
+            (fire.detail === undefined
+                ? ""
+                : ` detail=${JSON.stringify(fire.detail)}`));
+        // Test doubles may omit `host.otel`; the metric is best-effort.
+        const otel = this.engine.host.otel;
+        if (otel === undefined) {
+            return;
+        }
+        try {
+            otel.increment(REMINDER_FIRE_OUTCOME_METRIC, {
+                kind: fire.kind,
+                reason: fire.reason,
+                purpose: record.purpose,
+            });
+        }
+        catch (error) {
+            this.logger(`[agent-sdk] reminder fire_outcome metric failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     recordFromDescriptor(descriptor) {
         const now = new Date().toISOString();
         return {
@@ -817,16 +941,94 @@ export class ReminderRunner {
     }
     deliverPrompt(record) {
         return __awaiter(this, void 0, void 0, function* () {
+            return (yield this.deliverPromptFire(record)).result;
+        });
+    }
+    /**
+     * Where a prompt fire joins. The pod's own store first; on a hosted guest
+     * the durable mirror next, because the pod that armed the reminder is
+     * usually gone and the session lives only in storage. A restored session
+     * keeps its own principal (channel admissions may carry a sender), so the
+     * fire joins under that, never under {@link ReminderHostedGuestOptions.fireAuth}.
+     */
+    resolveFollowupTarget(record) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const local = yield this.resolveFollowupAuth(record.channelId, record.continuationToken);
+            if (local !== undefined) {
+                return { auth: local, reached: "session_joined" };
+            }
+            if (this.hostedGuest === undefined) {
+                return { auth: undefined, reached: "session_gone" };
+            }
+            // Materializes the durable record locally; a storage error propagates
+            // and the hosted admission retries the fire.
+            const restored = yield this.engine.hasContinuationSession(record.channelId, record.continuationToken);
+            if (!restored) {
+                return { auth: undefined, reached: "session_gone" };
+            }
             const auth = yield this.resolveFollowupAuth(record.channelId, record.continuationToken);
-            if (auth === undefined) {
-                // Under CP protocol, return stop and let the CP apply/CAS; do not
-                // mutate authoritative status from the guest mid-fire.
-                if (!this.usesControlPlaneProtocol) {
-                    yield this.disarm(record, "session_gone");
+            return auth === undefined
+                ? { auth: undefined, reached: "session_unreadable" }
+                : { auth, reached: "session_restored" };
+        });
+    }
+    deliverPromptFire(record) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const target = yield this.resolveFollowupTarget(record);
+            if (target.auth !== undefined) {
+                return this.promptDelivery(record, target.auth, target.reached);
+            }
+            if (target.reached === "session_unreadable") {
+                this.logger(`[agent-sdk] reminder "${record.id}" (${record.purpose}) durable session did not materialize locally; not opening a new one`);
+                return { result: { action: "stop" }, reason: "session_gone" };
+            }
+            if (this.hostedGuest !== undefined &&
+                this.channelUsesControlPlaneContinuation(record.channelId)) {
+                // No session on this pod and none in durable storage. Open one on the
+                // stored key the way an inbound event on a fresh key does, instead of
+                // consuming the fire with no turn.
+                const fireAuth = this.hostedGuest.fireAuth();
+                if (fireAuth === undefined) {
+                    return {
+                        result: {
+                            action: "skip",
+                            reschedule: { delay: REMINDER_SESSION_OPEN_RETRY_DELAY },
+                        },
+                        reason: "session_gone",
+                    };
                 }
-                return { action: "stop" };
+                try {
+                    return yield this.promptDelivery(record, fireAuth, "session_opened");
+                }
+                catch (error) {
+                    if (!(error instanceof SessionAuthError)) {
+                        throw error;
+                    }
+                    // A session landed on this key under another principal between the
+                    // lookup and the send. That does not change on retry, so stop
+                    // rather than let the control plane re-admit until its attempt cap.
+                    this.logger(`[agent-sdk] reminder "${record.id}" (${record.purpose}) cannot join session on its continuation: ${error.message}`);
+                    return { result: { action: "stop" }, reason: "session_gone" };
+                }
+            }
+            // Under CP protocol, return stop and let the CP apply/CAS; do not
+            // mutate authoritative status from the guest mid-fire.
+            if (!this.usesControlPlaneProtocol) {
+                yield this.disarm(record, "session_gone");
             }
-            return this.sendFollowup(record, buildFirePrompt(record), auth);
+            return { result: { action: "stop" }, reason: "session_gone" };
+        });
+    }
+    promptDelivery(record, auth, delivered) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const settle = {};
+            const result = yield this.sendFollowup(record, buildFirePrompt(record), auth, settle);
+            return {
+                result,
+                reason: result.action === "skip" ? ((_a = settle.skipReason) !== null && _a !== void 0 ? _a : "busy") : delivered,
+                turnStatus: settle.turnStatus,
+            };
         });
     }
     /**
@@ -859,29 +1061,55 @@ export class ReminderRunner {
             : channelContinuationIdentity((_a = project.channels.find(channel => channel.id === channelId)) === null || _a === void 0 ? void 0 : _a.definition);
         return continuationSource(identity) === "control-plane";
     }
-    sendFollowup(record, message, auth) {
+    /**
+     * Local and v1 track the turn in the background: the process outlives the
+     * fire. A hosted v2 guest waits for the turn and its durable writes first,
+     * because the control plane may stop the pod as soon as the fire's
+     * outcome is applied, and `delivered` must mean the turn ran.
+     */
+    settleFollowup(session, settle) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const completion = this.engine.waitForCompletion(session.id);
+            if (this.hostedGuest === undefined) {
+                this.engine.trackBackground(completion);
+                return;
+            }
+            const outcome = yield completion;
+            yield this.engine.drainSessionDurability(session.id);
+            if (settle !== undefined) {
+                settle.turnStatus = outcome.status;
+            }
+        });
+    }
+    sendFollowup(record, message, auth, settle) {
         return __awaiter(this, void 0, void 0, function* () {
             const sendOptions = this.followupSendOptions(record, auth);
             try {
                 const session = yield this.engine.send(record.channelId, message, sendOptions);
-                this.engine.trackBackground(this.engine.waitForCompletion(session.id));
+                yield this.settleFollowup(session, settle);
                 return { action: "delivered" };
             }
             catch (error) {
                 if (error instanceof SessionBusyError) {
                     if (record.busyPolicy === "skipIfBusy") {
+                        if (settle !== undefined) {
+                            settle.skipReason = "busy";
+                        }
                         return { action: "skip" };
                     }
                     yield this.whenSessionIdle(record.channelId, record.continuationToken);
                     try {
                         const session = yield this.engine.send(record.channelId, message, sendOptions);
-                        this.engine.trackBackground(this.engine.waitForCompletion(session.id));
+                        yield this.settleFollowup(session, settle);
                         return { action: "delivered" };
                     }
                     catch (retryError) {
                         this.logger(`[agent-sdk] reminder "${record.id}" followup failed after wait: ${retryError instanceof Error
                             ? retryError.message
                             : String(retryError)}`);
+                        if (settle !== undefined) {
+                            settle.skipReason = "followup_failed";
+                        }
                         return { action: "skip" };
                     }
                 }
@@ -904,9 +1132,13 @@ export class ReminderRunner {
             artifacts: this.engine.artifacts,
             followup(args) {
                 return __awaiter(this, void 0, void 0, function* () {
-                    const auth = yield self.resolveFollowupAuth(record.channelId, record.continuationToken);
+                    const { auth } = yield self.resolveFollowupTarget(record);
                     if (auth === undefined) {
-                        yield self.disarm(record, "session_gone");
+                        // Under the CP protocol the guest never writes reminder status;
+                        // the fire's `stop` outcome carries the reason instead.
+                        if (!self.usesControlPlaneProtocol) {
+                            yield self.disarm(record, "session_gone");
+                        }
                         throw new Error(`Reminder "${record.id}" followup: session gone for continuation`);
                     }
                     const result = yield self.sendFollowup(record, args.message, auth);

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;AAqDH,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAOhB,YAAY,EACb,MAAM,aAAa,CAAC;AAwGrB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAuDpE,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,iBAAiB,CAAC;AAUpE,OAAO,EAEL,wBAAwB,EAEzB,MAAM,sBAAsB,CAAC;AAO9B,OAAO,EAAsB,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAgB/E,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;CACvB;AAwCD,6EAA6E;AAC7E,MAAM,WAAW,0BAA0B;IACzC,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,yEAAyE;IACzE,aAAa,CAAC,EAAE,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;IAC5D,wEAAwE;IACxE,aAAa,CAAC,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC;CACxD;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,GAAE,YAAY,GAAG,0BAA+B,GACtD,OAAO,CAAC,gBAAgB,CAAC,CA6oC3B"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/internal/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqDH,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAOhB,YAAY,EACb,MAAM,aAAa,CAAC;AAwGrB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAuDpE,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,iBAAiB,CAAC;AAUpE,OAAO,EAEL,wBAAwB,EAEzB,MAAM,sBAAsB,CAAC;AAO9B,OAAO,EAAsB,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAgB/E,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;CACvB;AAwCD,6EAA6E;AAC7E,MAAM,WAAW,0BAA0B;IACzC,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,yEAAyE;IACzE,aAAa,CAAC,EAAE,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;IAC5D,wEAAwE;IACxE,aAAa,CAAC,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC;CACxD;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,GAAE,YAAY,GAAG,0BAA+B,GACtD,OAAO,CAAC,gBAAgB,CAAC,CAqpC3B"}

package/dist/internal/server.js

@@ -598,6 +598,13 @@ export function startServer(mounts_1) {
                 }),
                 architecture,
                 controlPlane: reminderControlPlane,
+                // Hosted admissions build their channel args with no request
+                // principal (`buildChannelHandlerArgs` → `auth: null`), so a fire that
+                // opens a session on a fresh pod uses the same one and a session
+                // restored from durable storage still matches.
+                hostedGuest: hostedReminderControlPlane === undefined
+                    ? undefined
+                    : { fireAuth: () => null },
             });
             const evalRuns = new EvalRunStore(project.rootDir, logger, 
             // Playground eval history mirrors onto the defineStorage evals table.

package/dist/memory.d.ts

@@ -68,6 +68,10 @@ export interface AgentStoreMemoryBackendOptions {
     sink?: FileSink;
     /** Rotation threshold, same meaning as {@link FileMemoryBackendOptions}. */
     maxJournalBytes?: number;
+    /** Backoff sleep override (tests). */
+    sleep?: (ms: number) => Promise<void>;
+    /** Jitter source override (tests). Returns [0, 1). */
+    random?: () => number;
 }
 /**
  * Journal on the deployment's Agent Store — durable across deploys, visible

package/dist/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,EAAqC,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAM9E,OAAO,KAAK,EAAe,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzE,sEAAsE;AACtE,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC,gDAAgD;AAChD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC/B,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB,CAAC;AAEF,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,UAAU,CACR,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAC5C,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,aAAa,CAgCf;AAED,MAAM,WAAW,8BAA8B;IAC7C,uEAAuE;IACvE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,8BAAmC,GAC3C,aAAa,CAsEf;AAqBD,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,CA0F1E"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,EAAqC,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAM9E,OAAO,KAAK,EAAe,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzE,sEAAsE;AACtE,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC,gDAAgD;AAChD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC/B,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB,CAAC;AAEF,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,UAAU,CACR,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAC5C,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,aAAa,CAgCf;AAED,MAAM,WAAW,8BAA8B;IAC7C,uEAAuE;IACvE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACvB;AAsBD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,8BAAmC,GAC3C,aAAa,CAgFf;AAqBD,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,CA0F1E"}

package/dist/memory.js

@@ -80,6 +80,24 @@ export function fileMemoryBackend(options = {}) {
         },
     };
 }
+/**
+ * CAS attempts per append. The journal is one deployment-wide key written by
+ * every engine pod, so under concurrent turn traffic the etag precondition
+ * loses races routinely; each retry needs headroom to land.
+ */
+const MEMORY_CAS_MAX_ATTEMPTS = 5;
+/**
+ * Jittered exponential backoff between CAS attempts. Retrying immediately is
+ * a fleet-wide stampede: every losing pod re-GETs the full journal and
+ * re-PUTs in lockstep, which multiplied reads ~65x on one deployment during
+ * the 2026-09-18 Agent Store read storm and tripped the store's
+ * per-service-account read limit (every pod shares the deployment
+ * credential). Jitter desynchronizes the writers so most retries land on the
+ * first or second attempt.
+ */
+function memoryCasBackoffMs(attempt, random) {
+    return 100 * Math.pow(2, attempt) * (0.5 + random());
+}
 /**
  * Journal on the deployment's Agent Store — durable across deploys, visible
  * on cloud VMs under the store mount. Appends are read-modify-write with
@@ -87,16 +105,20 @@ export function fileMemoryBackend(options = {}) {
  * `<stateRoot>/memory/journal.jsonl` for the workspace symlink read path.
  */
 export function agentStoreMemoryBackend(options = {}) {
-    var _a, _b;
+    var _a, _b, _c, _d;
     const sink = (_a = options.sink) !== null && _a !== void 0 ? _a : cursorHostedFiles();
     const maxJournalBytes = (_b = options.maxJournalBytes) !== null && _b !== void 0 ? _b : 5 * 1024 * 1024;
+    const sleep = (_c = options.sleep) !== null && _c !== void 0 ? _c : ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
+    const random = (_d = options.random) !== null && _d !== void 0 ? _d : Math.random;
     // Appends are chained per journal key (same shape as fileMemoryBackend);
-    // a failed append must not poison the chain for later turns.
+    // a failed append must not poison the chain for later turns. The chain
+    // serializes appends within this pod only — pods race each other on the
+    // shared key, which is what the CAS retry (with backoff) absorbs.
     const appendChains = new Map();
     const append = (record, ctx) => __awaiter(this, void 0, void 0, function* () {
         const key = agentStoreKeys.memoryJournal(ctx.agentName);
         const line = Buffer.from(`${JSON.stringify(record)}\n`, "utf8");
-        for (let attempt = 0; attempt < 3; attempt += 1) {
+        for (let attempt = 0; attempt < MEMORY_CAS_MAX_ATTEMPTS; attempt += 1) {
             const current = yield sink.get(key);
             const currentBody = current === undefined
                 ? new Uint8Array(0)
@@ -122,7 +144,9 @@ export function agentStoreMemoryBackend(options = {}) {
                 });
             }
             catch (error) {
-                if (error instanceof FileConflictError && attempt < 2) {
+                if (error instanceof FileConflictError &&
+                    attempt < MEMORY_CAS_MAX_ATTEMPTS - 1) {
+                    yield sleep(memoryCasBackoffMs(attempt, random));
                     continue;
                 }
                 throw error;