@cursor/july 0.1.45 → 0.1.46

package/src/ledger.ts

@@ -1,25 +1,40 @@
 /**
- * Session ledger — coordination only. The protocol library that drives
- * the `session/` and `ledger/` key families over a CAS-capable KV:
- * identity creation, lease claim/heartbeat/release, and the fenced
- * commit sequence. The durable inbox (pending events, mailbox payloads,
- * append/drain, the janitor) lands in a follow-up; see
- * `src/ledger/session-ledger.ts` for the trade-off this stage accepts.
+ * Session ledger — KV coordination with a durable inbox. The protocol
+ * library that drives the `session/`, `ledger/`, and `mailbox/` key
+ * families over a CAS-capable KV: identity creation, event append,
+ * lease claim/heartbeat/release, fenced commit, drain, the janitor
+ * loop, and the orphan sweep.
  */
 
+export type {
+  JanitorClaimedSession,
+  JanitorRunResult,
+  LedgerJanitor,
+  LedgerJanitorOptions,
+} from "./ledger/janitor.js";
+export {
+  createLedgerJanitor,
+  DEFAULT_JANITOR_INTERVAL_MS,
+} from "./ledger/janitor.js";
 export type {
   ClaimResult,
   CommitArgs,
   CommitResult,
+  DrainResult,
   EnsureSessionResult,
   HeartbeatResult,
+  LedgerEvent,
+  LedgerEventInput,
   LedgerLease,
   LedgerSnapshot,
   SessionIdentity,
   SessionLedgerKv,
   SessionLedgerOptions,
+  SweepOrphansArgs,
+  SweepOrphansResult,
 } from "./ledger/session-ledger.js";
 export {
+  DEFAULT_ORPHAN_TTL_MS,
   HEARTBEAT_INTERVAL_MS,
   LEASE_TTL_MS,
   LedgerCasExhaustedError,

package/src/storage-backends/cursor-hosted.ts

@@ -129,8 +129,10 @@ type CursorHostedStorageMethods = Required<
 //   AND version = expected`, conflict returns the current row (or
 //   `current: null` when the row is gone).
 // - `POST /internal/agent-serve/storage/kv/list-keys`
-//   `{ prefix }` → `{ keys }` ({@link KvListKeysResponse}) in ascending
-//   key order (prefix scan on the `(deployment_id, key)` primary key).
+//   `{ prefix }` → `{ keys, truncated }` ({@link KvListKeysResponse}) in
+//   ascending key order (prefix scan on the `(deployment_id, key)`
+//   primary key). `truncated: true` means the scan hit the server's row
+//   cap and the list is incomplete; this client throws on it.
 
 /** Wire shape of the `get-with-version` route. `null` ⇒ JSON `undefined`. */
 export interface KvGetWithVersionResponse {
@@ -151,6 +153,11 @@ export interface KvCasResponse {
 /** Wire shape of the `list-keys` route. */
 export interface KvListKeysResponse {
   keys: string[];
+  /**
+   * Set when the scan hit the server's row cap and `keys` is incomplete.
+   * Additive: older servers omit it (treated as `false`).
+   */
+  truncated?: boolean;
 }
 
 function toCasResult(response: KvCasResponse): KvCasResult {
@@ -305,6 +312,14 @@ export function cursorHostedStorage(
           "/internal/agent-serve/storage/kv/list-keys",
           { prefix }
         );
+        if (result.truncated === true) {
+          // Callers (the ledger janitor above all) treat the result as
+          // the complete key set; a silently capped scan means silently
+          // unrecovered sessions. Fail loudly until pagination lands.
+          throw new Error(
+            `cursorHostedStorage: listKeys("${prefix}") exceeded the server's row cap and was truncated; the result is incomplete`
+          );
+        }
         return result.keys;
       },
     },

package/src/types.ts

@@ -254,14 +254,15 @@ export interface AgentConfig {
  * - `"resident"` (default): the in-process session engine owns delivery —
  *   today's behavior, unchanged.
  * - `"ledger"`: every delivery coordinates through the KV session ledger
- *   before its turn runs: session identity, a one-writer-per-session
- *   lease with generation fencing, and a fenced commit sequence.
- *   Requires a store with conditional writes (the `cas` group on
+ *   before its turn runs: the event parks durably in the session mailbox
+ *   (the source ack point moves after that write), a one-writer-per-session
+ *   lease with generation fencing serializes turns, and drained batches
+ *   commit through a fenced sequence. A delivery that finds the lease
+ *   held walks away; the holder drains the parked event, and the janitor
+ *   recovers sessions whose holder died. Requires a store with
+ *   conditional writes and prefix listing (the `cas` group on
  *   `defineStorage`, or an explicit CAS-capable override); startup fails
- *   fast otherwise. This stage is coordination only — there is no
- *   durable inbox yet, so an event arriving while the lease is held
- *   waits in-process and a crash loses it exactly as resident serving
- *   does. The durable mailbox lands in a follow-up.
+ *   fast otherwise.
  */
 export type AgentServingMode = "resident" | "ledger";
 
@@ -816,6 +817,12 @@ export interface ToolContext {
    * `sessionId` (and `turnId` when known).
    */
   artifacts: ArtifactsApi;
+  /**
+   * Append a session event onto this call's in-flight turn. Same shape as a
+   * Task subagent stream (`parentCallId`, `subagent.called` /
+   * `subagent.completed`). Omitted for scratch `callTool` with no session.
+   */
+  emit?: (payload: SessionEventPayload) => void;
 }
 
 /**
@@ -1471,7 +1478,11 @@ export interface ChannelSession {
    */
   readonly coalesced?: boolean;
   readonly info: SessionInfo;
-  /** Replay recorded events from `startIndex`, then follow live (NDJSON). */
+  /**
+   * Replay recorded events from `startIndex`, then follow live (NDJSON).
+   * A handle from `send()` defaults `startIndex` to this admission so a
+   * resumed continuation does not replay earlier turns.
+   */
   getEventStream(options?: {
     startIndex?: number;
   }): Promise<ReadableStream<Uint8Array>>;