@cursor/july 0.1.45 → 0.1.46

package/dist/internal/ledger-serving.d.ts

@@ -1,100 +1,168 @@
 /**
- * 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).
  */
 import type { SessionLedger } from "../ledger/session-ledger.js";
-import type { ChannelSession, SendMessageOptions } from "../types.js";
-/** Wait between claim retries while another holder has the lease. */
-export declare 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 declare const CLAIM_WAIT_TIMEOUT_MS: number;
-/** The `send` options a ledger delivery carries to the resident turn. */
-export type LedgerDeliverOptions = SendMessageOptions & {
-    mode?: "chat" | "task";
-};
-/** One delivery handed back to the engine's resident path. */
-export interface LedgerTurnRequest {
+import type { AgentCloudOptions, AuthContext, ChannelSession, JsonValue, SendMessageOptions, SessionPurpose } from "../types.js";
+/** The JSON payload stored in `mailbox/<sessionId>/<eventId>`. */
+export interface LedgerDeliveryEnvelope {
     channelId: string;
     continuationToken: string;
     message: string;
-    options: LedgerDeliverOptions;
+    auth: AuthContext | null;
+    title?: string;
+    state?: JsonValue;
+    mode?: "chat" | "task";
+    purpose?: SessionPurpose;
+    /**
+     * Isolation-relevant per-send overrides, reapplied on the resident
+     * send at drain. Absent on envelopes parked by earlier builds — the
+     * drain then behaves as those builds did (agent-default runtime/cwd).
+     */
+    workspaceDir?: string;
+    cloud?: AgentCloudOptions;
 }
+/** The `send` options the envelope can carry through the mailbox. */
+export type LedgerDeliverOptions = SendMessageOptions & {
+    mode?: "chat" | "task";
+};
 export interface LedgerServingOptions {
     ledger: SessionLedger;
     /**
-     * Run one delivery as a resident-path turn (the engine's `send` with
-     * the internal ledger-delivery flag). Must resolve once the turn is
-     * admitted; the pump awaits `waitForCompletion` itself.
+     * Run one drained event as a resident-path turn (the engine's `send`
+     * with the internal `fromLedgerPump` flag). Must resolve once the turn
+     * is admitted; the pump awaits `waitForCompletion` itself.
      */
-    deliverTurn: (request: LedgerTurnRequest) => Promise<ChannelSession>;
+    deliverTurn: (envelope: LedgerDeliveryEnvelope) => Promise<ChannelSession>;
+    /** Engine continuation lookup (local index + lazy storage restore). */
+    findSession: (channelId: string, continuationToken: string) => Promise<ChannelSession | undefined>;
     logger?: (line: string) => void;
-    /** Lease heartbeat cadence while the turn runs (default 10s). */
+    /** Lease heartbeat cadence while turns run (default 10s). */
     heartbeatIntervalMs?: number;
-    /** Claim retry cadence while the lease is held (default 250ms). */
-    claimRetryDelayMs?: number;
-    /** Give-up bound for lease waiting (default 2× lease TTL). */
-    claimWaitTimeoutMs?: number;
+    /** Janitor scan cadence (default `DEFAULT_JANITOR_INTERVAL_MS`). */
+    janitorIntervalMs?: number;
     clock?: () => number;
-    /** Injectable wait (tests use short real delays; keep them tiny). */
-    sleep?: (ms: number) => Promise<void>;
 }
 export declare class LedgerServing {
     private readonly ledger;
     private readonly deliverTurn;
+    private readonly findSession;
     private readonly logger;
     private readonly heartbeatIntervalMs;
-    private readonly claimRetryDelayMs;
-    private readonly claimWaitTimeoutMs;
     private readonly clock;
-    private readonly sleep;
-    /**
-     * Per-ledger-session in-process serialization: local concurrent sends
-     * queue here instead of spinning claim retries against our own lease.
-     */
-    private readonly chains;
+    private readonly janitor;
+    /** One pump per ledger session — the in-process face of the lease. */
+    private readonly pumps;
+    /** Fire-and-forget re-pump checks, awaited on close. */
+    private readonly background;
     constructor(options: LedgerServingOptions);
-    /** Settle every queued and in-flight delivery. */
+    /** Start the janitor loop (recovers expired-lease sessions). */
+    start(): void;
+    /** Stop the janitor and settle in-flight pumps and re-pump checks. */
     close(): Promise<void>;
     /**
-     * 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: string, message: string, options: LedgerDeliverOptions): Promise<ChannelSession>;
-    /** Chain a delivery behind the session's in-flight ones. */
-    private enqueue;
-    /** claim (waiting) → resident turn → commit-release. */
-    private serveOne;
     /**
-     * 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).
+     * 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.
+     */
+    private parkedSession;
+    /**
+     * 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.
+     */
+    private resolveDeliverHandle;
+    /**
+     * 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.
+     */
+    private resolveSourceTs;
+    /**
+     * 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.
+     */
+    private warnOnDroppedOptions;
+    /**
+     * 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.
+     */
+    private servePending;
+    /** Claim-or-defer entry used after an append and after a pump settles. */
+    private runPump;
+    /** Janitor hand-off: the claim already happened, just run the turns. */
+    private serveClaimed;
+    /**
+     * Re-pump after the previous holder settled, covering the release window
+     * where an append landed after that holder's final commit.
+     */
+    private repumpIfPending;
+    /** Register a pump in the per-session map for its lifetime. */
+    private track;
+    /**
+     * 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).
      */
-    private claimWithWait;
+    private runClaimedTurns;
 }
 /** Mint the lease holder id for this process. */
 export declare function newLedgerPodId(): string;

package/dist/internal/ledger-serving.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ledger-serving.d.ts","sourceRoot":"","sources":["../../src/internal/ledger-serving.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAMjE,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGtE,qEAAqE;AACrE,eAAO,MAAM,oBAAoB,MAAM,CAAC;AACxC;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAyB,CAAC;AAE9D,yEAAyE;AACzE,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GAAG;IACtD,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,CAAC;AAEF,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,oBAAoB,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,WAAW,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACrE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB,qEAAqE;IACrE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAE9D,YAAY,OAAO,EAAE,oBAAoB,EAaxC;IAED,kDAAkD;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3B;IAED;;;;;OAKG;IACG,OAAO,CACX,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAazB;IAED,4DAA4D;IAC5D,OAAO,CAAC,OAAO;IAoBf,wDAAwD;YAC1C,QAAQ;IAsDtB;;;;;;OAMG;YACW,aAAa;CAiB5B;AAED,iDAAiD;AACjD,wBAAgB,cAAc,IAAI,MAAM,CAEvC"}
+{"version":3,"file":"ledger-serving.d.ts","sourceRoot":"","sources":["../../src/internal/ledger-serving.ts"],"names":[],"mappings":"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"}