@cursor/july 0.1.45 → 0.1.46

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/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,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"}

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";
@@ -1450,7 +1450,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] }),

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

@@ -23,9 +23,7 @@ export { SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
 export declare class SessionBusyError extends Error {
     constructor(sessionId: string);
 }
-export declare class SessionAuthError extends Error {
-    constructor(sessionId: string);
-}
+export { SessionAuthError } from "./auth.js";
 export declare class UnknownChannelError extends Error {
     constructor(channelId: string);
 }
@@ -71,10 +69,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
@@ -115,12 +114,13 @@ export interface EngineResolvedConnection {
 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;
 }
 export declare class SessionEngine {
     readonly project: AgentProject;
@@ -201,7 +201,7 @@ export declare class SessionEngine {
     constructor(options: SessionEngineOptions);
     /**
      * 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;
@@ -218,13 +218,14 @@ export declare 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;
     /**