@cursor/july 0.1.76 → 0.1.78

package/src/channels/origin/origin-webhook.ts

@@ -32,8 +32,6 @@ const V1ED_TIMESTAMP_TOLERANCE_SECONDS = 5 * 60;
  */
 const MAX_V1ED_CANDIDATE_SIGNATURES = 1;
 
-const JWKS_CACHE_TTL_MS = 5 * 60 * 1000;
-
 export type OriginJwk = Record<string, unknown>;
 
 export type OriginWebhookHeaders = {
@@ -131,41 +129,115 @@ export function verifyV1edWebhookPayload(args: {
   return false;
 }
 
+function cacheControlDeltaMs(
+  cacheControl: string | null | undefined,
+  directive: "max-age" | "stale-if-error"
+): number | undefined {
+  if (cacheControl == null || cacheControl === "") {
+    return undefined;
+  }
+  const match = new RegExp(`(?:^|,)\\s*${directive}\\s*=\\s*(\\d+)`, "i").exec(
+    cacheControl
+  );
+  if (match === null) {
+    return undefined;
+  }
+  return Number(match[1]) * 1000;
+}
+
+/**
+ * RFC 9111 `max-age` (seconds → ms) from a Cache-Control header.
+ * Does not read `s-maxage`. Missing or unparsable → `undefined`.
+ */
+export function cacheControlMaxAgeMs(
+  cacheControl: string | null | undefined
+): number | undefined {
+  return cacheControlDeltaMs(cacheControl, "max-age");
+}
+
+/**
+ * RFC 5861 `stale-if-error` (seconds → ms). Missing → `undefined` (no
+ * fail-open after `max-age`).
+ */
+export function cacheControlStaleIfErrorMs(
+  cacheControl: string | null | undefined
+): number | undefined {
+  return cacheControlDeltaMs(cacheControl, "stale-if-error");
+}
+
 let jwksCache:
-  | { apiBaseUrl: string; keys: OriginJwk[]; fetchedAtMs: number }
+  | {
+      apiBaseUrl: string;
+      keys: OriginJwk[];
+      freshUntilMs: number;
+      staleUntilMs: number;
+    }
   | undefined;
 
-/** Fetch (and cache for 5 minutes) the Origin signing JWKS. */
+export type FetchOriginJwksOptions = {
+  /** Skip the in-memory hit and call `/v1/origin/keys` (used after a verify miss). */
+  force?: boolean;
+};
+
+/**
+ * Return the in-memory Origin signing JWKS.
+ *
+ * Freshness is the JWKS response `Cache-Control: max-age`. After that, or
+ * when `force` is set, refetch. A failed refetch returns the last keys only
+ * while `stale-if-error` still applies; otherwise it throws (including a
+ * cold-cache miss).
+ */
 export async function fetchOriginJwks(
   apiBaseUrl: string,
-  fetchImpl: typeof fetch = fetch
+  fetchImpl: typeof fetch = fetch,
+  options?: FetchOriginJwksOptions
 ): Promise<readonly OriginJwk[]> {
   const now = Date.now();
   if (
+    options?.force !== true &&
     jwksCache !== undefined &&
     jwksCache.apiBaseUrl === apiBaseUrl &&
-    now - jwksCache.fetchedAtMs < JWKS_CACHE_TTL_MS
+    now < jwksCache.freshUntilMs
   ) {
     return jwksCache.keys;
   }
-  const response = await fetchImpl(
-    `${apiBaseUrl.replace(/\/+$/, "")}/v1/origin/keys`
-  );
-  if (!response.ok) {
-    throw new Error(`Origin JWKS fetch failed: status=${response.status}`);
-  }
-  const body: unknown = await response.json().catch(() => undefined);
-  const keys =
-    typeof body === "object" &&
-    body !== null &&
-    Array.isArray((body as Record<string, unknown>).keys)
-      ? ((body as Record<string, unknown>).keys as OriginJwk[])
-      : [];
-  if (keys.length === 0) {
-    throw new Error("Origin JWKS fetch returned no keys");
+  try {
+    const response = await fetchImpl(
+      `${apiBaseUrl.replace(/\/+$/, "")}/v1/origin/keys`
+    );
+    if (!response.ok) {
+      throw new Error(`Origin JWKS fetch failed: status=${response.status}`);
+    }
+    const body: unknown = await response.json().catch(() => undefined);
+    const keys =
+      typeof body === "object" &&
+      body !== null &&
+      Array.isArray((body as Record<string, unknown>).keys)
+        ? ((body as Record<string, unknown>).keys as OriginJwk[])
+        : [];
+    if (keys.length === 0) {
+      throw new Error("Origin JWKS fetch returned no keys");
+    }
+    const cacheControl = response.headers.get("cache-control");
+    const maxAgeMs = cacheControlMaxAgeMs(cacheControl) ?? 0;
+    const staleIfErrorMs = cacheControlStaleIfErrorMs(cacheControl) ?? 0;
+    jwksCache = {
+      apiBaseUrl,
+      keys,
+      freshUntilMs: now + maxAgeMs,
+      staleUntilMs: now + maxAgeMs + staleIfErrorMs,
+    };
+    return keys;
+  } catch (error) {
+    if (
+      jwksCache !== undefined &&
+      jwksCache.apiBaseUrl === apiBaseUrl &&
+      now < jwksCache.staleUntilMs
+    ) {
+      return jwksCache.keys;
+    }
+    throw error;
   }
-  jwksCache = { apiBaseUrl, keys, fetchedAtMs: now };
-  return keys;
 }
 
 export interface VerifyOriginWebhookOptions {
@@ -183,14 +255,28 @@ export async function verifyOriginWebhook(
   options?: VerifyOriginWebhookOptions
 ): Promise<void> {
   const apiBaseUrl = options?.apiBaseUrl ?? DEFAULT_ORIGIN_API_BASE_URL;
-  const keys = await fetchOriginJwks(apiBaseUrl, options?.fetchImpl ?? fetch);
+  const fetchImpl = options?.fetchImpl ?? fetch;
+  const keys = await fetchOriginJwks(apiBaseUrl, fetchImpl);
   if (
-    !verifyV1edWebhookPayload({
+    verifyV1edWebhookPayload({
       publicJwks: keys,
       body,
       headers,
       nowMs: options?.nowMs,
     })
+  ) {
+    return;
+  }
+  const refreshed = await fetchOriginJwks(apiBaseUrl, fetchImpl, {
+    force: true,
+  });
+  if (
+    !verifyV1edWebhookPayload({
+      publicJwks: refreshed,
+      body,
+      headers,
+      nowMs: options?.nowMs,
+    })
   ) {
     throw new Error("Origin webhook signature verification failed");
   }

package/src/index.ts

@@ -96,12 +96,6 @@ export {
   UnknownToolError,
 } from "./internal/session-engine.js";
 export { createMemoryKv, memoryCasTable } from "./kv/memory-kv.js";
-export {
-  LedgerCasExhaustedError,
-  LedgerFencedError,
-  SessionLedger,
-  supportsSessionLedgerKv,
-} from "./ledger.js";
 export type { MemoryBackend, TurnMemoryRecord } from "./memory.js";
 export {
   agentStoreMemoryBackend,

package/src/internal/discovery.ts

@@ -29,7 +29,6 @@ import {
   type AgentProject,
   type AgentProjectInfo,
   type AgentRuntime,
-  type AgentServingMode,
   type ArtifactsDefinition,
   type BuiltinToolsConfig,
   type ChannelDefinition,
@@ -194,9 +193,9 @@ export async function loadAgentProjects(
     );
   }
   const results: Array<{ slug: string; project: AgentProject }> = [];
-  // Storage namespaces (session mirror, host kv, durable-session ledger)
-  // key on the project NAME, not the mount slug — two co-hosted agents
-  // sharing a name would silently share sessions and coordination state.
+  // Storage namespaces (session mirror, host kv) key on the project
+  // NAME, not the mount slug — two co-hosted agents sharing a name would
+  // silently share sessions and KV state.
   const slugByName = new Map<string, string>();
   for (const child of children) {
     const project = await loadAgentProject(child.dir, options);
@@ -506,7 +505,6 @@ async function loadAgent(
         };
   const hosting = resolveHosting(ctx, agentDir, config?.hosting);
   const concurrency = resolveConcurrency(ctx, agentDir, config?.concurrency);
-  const serving = resolveServing(ctx, agentDir, config?.serving);
 
   if (runtime === "cloud") {
     warnCloudRuntimeLimitations(ctx, agentDir, {
@@ -531,7 +529,6 @@ async function loadAgent(
     ...(allowedTools === undefined ? {} : { allowedTools }),
     hosting,
     concurrency,
-    serving,
     tools,
     skills,
     connections,
@@ -540,27 +537,6 @@ async function loadAgent(
   };
 }
 
-/**
- * Validate the authored serving mode. An unrecognized value is an error
- * diagnostic and falls back to undefined (resident) — a typo must not
- * silently opt an agent into (or out of) ledger coordination.
- */
-function resolveServing(
-  ctx: DiscoveryContext,
-  agentDir: string,
-  serving: AgentServingMode | undefined
-): AgentServingMode | undefined {
-  if (serving === undefined || serving === "resident" || serving === "ledger") {
-    return serving;
-  }
-  ctx.diagnostics.push({
-    severity: "error",
-    path: displayPath(ctx, join(agentDir, "agent.ts")),
-    message: `serving must be "resident" or "ledger"; got ${JSON.stringify(serving)}.`,
-  });
-  return undefined;
-}
-
 /** Absolute harness cwd parent, or undefined when unset / blank. */
 function resolveAgentCwd(
   ctx: DiscoveryContext,

package/src/internal/distribution.ts

@@ -112,7 +112,6 @@ export const AUTHORING_ENTRY_FILES: ReadonlyArray<
   ["artifacts", "artifacts.js"],
   ["kv", "kv.js"],
   ["kv/memory", "kv/memory-kv.js"],
-  ["ledger", "ledger.js"],
   ["storage", "storage.js"],
   ["storage/file-kv", "storage-backends/file-kv.js"],
   ["storage/cursor-hosted", "storage-backends/cursor-hosted.js"],

package/src/internal/session-engine.ts

@@ -25,12 +25,6 @@ import {
 } from "../channels/slack/nudge-store.js";
 import { resolveDedicatedSlackHostBinding } from "../channels/slack/slack-channel.js";
 import { isCursorHostedFilesAvailable } from "../files-backends/cursor-hosted.js";
-import {
-  SessionLedger,
-  type SessionLedgerKv,
-  supportsSessionLedgerKv,
-} from "../ledger/session-ledger.js";
-import { fileKv } from "../storage-backends/file-kv.js";
 import {
   type AgentProject,
   type ApprovalDecision,
@@ -48,7 +42,6 @@ import {
   DIRECT_TOOL_CALL_CHANNEL_ID,
   type HookHandler,
   type HostContext,
-  type HostKvApi,
   type HttpChannelDefinition,
   isHostOauthConnectionTransport,
   isSymbolicConnectionTransport,
@@ -88,11 +81,6 @@ import {
   mapSdkTokenUsage,
 } from "./cloud-turn-cost.js";
 import { isDevMode } from "./dev-mode.js";
-import {
-  ledgerKeyPrefix,
-  namespacedKv,
-  storageCasKv,
-} from "./durable-session-store.js";
 import { type EventLogMemoryStats, EventLogStore } from "./event-log.js";
 import { TurnEventMapper } from "./event-mapper.js";
 import { selectFrameworkStorageDefinition } from "./framework-storage-selection.js";
@@ -111,7 +99,6 @@ import {
   newToolCallId,
 } from "./ids.js";
 import { validateToolInput } from "./json-schema.js";
-import { LedgerServing, newLedgerPodId } from "./ledger-serving.js";
 import { McpHost } from "./mcp-host.js";
 import type { OtelCollector } from "./otel/collector.js";
 import {
@@ -158,7 +145,7 @@ export class SessionBusyError extends Error {
   }
 }
 
-// Defined in auth.js (the ledger pump needs it without importing this
+// Defined in auth.js (HTTP/session-store callers import it without this
 // module); re-exported here because this is its historical public home.
 export { SessionAuthError } from "./auth.js";
 
@@ -235,22 +222,6 @@ export interface SessionEngineOptions {
    * stub; production uses billed usage events when an agent id is known.
    */
   estimateTurnCost?: EstimateTurnCostFn;
-  /**
-   * 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 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
-   * no authored storage — a file store under `<stateRoot>/ledger-kv`
-   * (single-process correctness only). An authored storage backend
-   * *without* `cas` fails fast. Ignored for resident-mode agents.
-   */
-  durableSessionStore?: HostKvApi;
   /** Process-level OTel collector; observe-only, never fatal. */
   otel?: OtelCollector;
   /** Process-level meter for {@link HostContext.otel}. Absent → no-op counters. */
@@ -290,14 +261,6 @@ interface ActiveToolContext {
 
 export interface EngineSendOptions extends SendMessageOptions {
   mode?: "chat" | "task";
-  /**
-   * 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.
-   */
-  fromLedgerPump?: boolean;
 }
 
 interface CoalescedQueuedTurn {
@@ -400,12 +363,6 @@ export class SessionEngine {
   private readonly cloudCostBackfillDone = new Set<string>();
   /** Deduped in-flight cloud cost backfills, keyed by session id. */
   private readonly cloudCostBackfill = new Map<string, Promise<void>>();
-  /**
-   * Ledger-mode delivery seam; set only when the agent declares
-   * `serving: "ledger"`. When present, {@link send} routes every
-   * non-delivery call through the ledger's claim → turn → commit.
-   */
-  private readonly ledgerServing: LedgerServing | undefined;
 
   constructor(options: SessionEngineOptions) {
     this.project = options.project;
@@ -499,8 +456,6 @@ export class SessionEngine {
     for (const channel of options.project.channels) {
       this.channelsById.set(channel.id, channel.definition);
     }
-    this.ledgerServing = this.buildLedgerServing(options);
-    this.ledgerServing?.start();
     this.stopMemoryTelemetry = shouldStartProcessMemoryTelemetry()
       ? startProcessMemoryTelemetry({
           agentName: options.project.name,
@@ -511,113 +466,6 @@ export class SessionEngine {
       : undefined;
   }
 
-  /**
-   * Ledger-mode wiring (`serving: "ledger"`): resolve a CAS-capable
-   * durable-session store and build the event pump. Resident agents
-   * (the default) return undefined and never touch ledger keys.
-   */
-  private buildLedgerServing(
-    options: SessionEngineOptions
-  ): LedgerServing | undefined {
-    if (options.project.agent.serving !== "ledger") {
-      return undefined;
-    }
-    // The handle is already agent-scoped (resolveDurableSessionStore):
-    // two ledger-mode agents sharing one backend never resolve to each
-    // other's sessions or janitor-claim each other's parked envelopes.
-    const ledgerKv = this.resolveDurableSessionStore(options);
-    return new LedgerServing({
-      ledger: new SessionLedger({ kv: ledgerKv, podId: newLedgerPodId() }),
-      deliverTurn: (envelope) =>
-        this.send(envelope.channelId, envelope.message, {
-          continuationToken: envelope.continuationToken,
-          auth: envelope.auth,
-          ...(envelope.title === undefined ? {} : { title: envelope.title }),
-          ...(envelope.state === undefined ? {} : { state: envelope.state }),
-          ...(envelope.mode === undefined ? {} : { mode: envelope.mode }),
-          ...(envelope.purpose === undefined
-            ? {}
-            : { purpose: envelope.purpose }),
-          // Isolation overrides ride the envelope: without them the
-          // drained turn would run local with the default harness cwd
-          // instead of the cloud VM / channel worktree the sender bound.
-          ...(envelope.workspaceDir === undefined
-            ? {}
-            : { workspaceDir: envelope.workspaceDir }),
-          ...(envelope.cloud === undefined ? {} : { cloud: envelope.cloud }),
-          fromLedgerPump: true,
-        }),
-      findSession: async (channelId, continuationToken) => {
-        let record = await this.sessions.findByContinuation(
-          channelId,
-          continuationToken
-        );
-        if (record === undefined) {
-          record = await this.restoreSessionByContinuation(
-            channelId,
-            continuationToken
-          );
-        }
-        return record === undefined
-          ? undefined
-          : this.channelSession(record.sessionId, record, false);
-      },
-      logger: this.logger,
-    });
-  }
-
-  /**
-   * Pick the KV the ledger coordinates on, in precedence order:
-   *
-   * 1. `options.durableSessionStore` — an explicit store separate from
-   *    agent state (advanced deployments, tests).
-   * 2. The authored storage backend (`agent/storage.ts`) when it
-   *    implements the `cas` group — one backend serves both the storage
-   *    API and the durable session API.
-   * 3. No authored storage: a file store under `<stateRoot>/ledger-kv`
-   *    (same place resident state lives; single-process only).
-   *
-   * 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 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/…` / `mailbox/…` keys; namespacing is this
-   * boundary's job, exactly like `host.kv`'s agent scoping.
-   */
-  private resolveDurableSessionStore(
-    options: SessionEngineOptions
-  ): SessionLedgerKv {
-    const namespace = ledgerKeyPrefix(options.project.name);
-    const explicit = options.durableSessionStore;
-    if (explicit !== undefined) {
-      if (!supportsSessionLedgerKv(explicit)) {
-        throw new Error(
-          `Agent "${options.project.name}" declares serving: "ledger", but the configured durableSessionStore is not CAS-capable (getWithVersion / putIfAbsent / putIfVersion / listKeys). Provide a store implementing HostKvCasApi (see @cursor/july/kv).`
-        );
-      }
-      return namespacedKv(explicit, namespace);
-    }
-    const casArgs = {
-      agentName: options.project.name,
-      projectRoot: options.project.rootDir,
-    };
-    const authored = options.project.storage;
-    if (authored !== undefined) {
-      if (authored.cas === undefined) {
-        throw new Error(
-          `Agent "${options.project.name}" declares serving: "ledger", which needs conditional writes, but the storage backend in agent/storage.ts does not implement the cas group. Add cas: {...} to defineStorage (fileKv and cursorHostedStorage already include it), or pass an explicit durableSessionStore.`
-        );
-      }
-      return namespacedKv(storageCasKv(authored, casArgs), namespace);
-    }
-    const fallback = fileKv({ dir: join(options.stateRoot, "ledger-kv") });
-    return namespacedKv(storageCasKv(fallback, casArgs), namespace);
-  }
-
   /**
    * Attach serve-time resolved connections (peers, Cursor account bridge).
    * They join the per-turn SDK `mcpServers` map (loopback URL for local
@@ -892,12 +740,6 @@ export class SessionEngine {
     message: string,
     options: EngineSendOptions = {}
   ): Promise<ChannelSession> {
-    // Ledger-mode agents park the event durably and coordinate through
-    // the session lease before any turn runs; only the pump's own
-    // lease-holding deliveries fall through to the resident path.
-    if (this.ledgerServing !== undefined && options.fromLedgerPump !== true) {
-      return this.ledgerServing.deliver(channelId, message, options);
-    }
     const auth = options.auth ?? null;
     let existing =
       options.continuationToken === undefined
@@ -1008,13 +850,6 @@ export class SessionEngine {
     };
     await this.sessions.save(record);
     this.storage?.sessionRecord(record);
-    // Ledger serving: another pod can follow up mid-turn, so the session
-    // identity (record + continuation index) must hit the shared store
-    // before we return a session id. Default turnEnd flush is too late.
-    if (this.ledgerServing !== undefined && this.storage !== undefined) {
-      this.storage.flushSession(record.sessionId);
-      await this.storage.whenIdle();
-    }
     await this.appendEvent(record.sessionId, {
       type: "session.started",
       data: { channelId },
@@ -3841,8 +3676,6 @@ export class SessionEngine {
   async close(): Promise<void> {
     this.stopMemoryTelemetry?.();
     this.approvals.cancelAll("deny");
-    // Ledger deliveries spawn turns, so settle them before activeTurns.
-    await this.ledgerServing?.close();
     await Promise.allSettled([...this.activeTurns.values()]);
     await Promise.allSettled([...this.backgroundWork]);
     await Promise.allSettled([...this.dispatchChains.values()]);

package/src/kv/memory-kv.ts

@@ -4,8 +4,7 @@
  * `@cursor/july/kv/memory`.
  *
  * The memory KV *is* the dev shim: tests and local runs exercise the
- * same CAS coordination paths that hosted serving uses, not a mock of an
- * RPC. Values are deep-copied on both write and
+ * CAS contract, not a mock of an RPC. Values are deep-copied on both write and
  * read so callers can never observe (or cause) shared-reference mutation.
  */
 
@@ -86,14 +85,6 @@ export function createMemoryKv(): HostKvCasApi {
  * fixtures, an off-hosting no-op sink). Non-durable and process-local by
  * construction; a real deployment backend should implement CAS against
  * its own store instead.
- *
- * **Never pair this with `serving: "ledger"` on a real backend.** The
- * ledger derives its coordination store from the whole storage config,
- * so a durable plain backend with a memory `cas` group silently voids
- * ack-after-durable: leases, heads, and pending indexes live only in
- * this process and vanish on restart while payload blobs go through the
- * plain methods. Ledger state must live in the same durable store as
- * the blobs.
  */
 export function memoryCasTable(): StorageCasTable {
   const kv = createMemoryKv();

package/src/kv.ts

@@ -2,9 +2,8 @@
  * The CAS-capable KV **interface** — `@cursor/july/kv`.
  *
  * This module is implementation-free on purpose: it is the contract a
- * bring-your-own KV implements so coordination protocols (conditional
- * writes are the substrate for the upcoming session ledger) can run on
- * it. {@link HostKvCasApi} is the conditional-write superset of the plain
+ * bring-your-own KV implements so conditional writes can run on it.
+ * {@link HostKvCasApi} is the conditional-write superset of the plain
  * {@link HostKvApi}; {@link supportsKvCas} is the runtime probe for
  * stores of unknown provenance — a `defineStorage` backend declares CAS
  * through its `cas` group instead, so it never needs probing.

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

@@ -313,9 +313,9 @@ export function cursorHostedStorage(
           { 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.
+          // Callers treat the result as the complete key set; a silently
+          // capped scan hides missing keys. Fail loudly until pagination
+          // lands.
           throw new Error(
             `cursorHostedStorage: listKeys("${prefix}") exceeded the server's row cap and was truncated; the result is incomplete`
           );

package/src/storage-protocol.ts

@@ -4,9 +4,7 @@
  * `backend/server/src/agentServe/durableSessionProtocol.ts`) so a dashboard
  * list can read Bugbot KV without importing `@cursor/july`.
  *
- * Additive JSON only — unknown fields are ignored. Do not put ledger
- * (`durable-session/`) types here; those are coordination-only and must not
- * appear in the CP session list.
+ * Additive JSON only — unknown fields are ignored.
  */
 
 import { createHash } from "node:crypto";
@@ -19,8 +17,7 @@ export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
 
 /**
  * Exact session-record keys: `agentkit/v1/{agent}/session/{sessionId}`.
- * Rejects `session-events/`, `durable-session/`, and the CP-owned `_cp`
- * agent name.
+ * Rejects `session-events/` and the CP-owned `_cp` agent name.
  */
 const DURABLE_SESSION_RECORD_KEY_RE =
   /^agentkit\/v1\/([^/]+)\/session\/([^/]+)$/;
@@ -109,9 +106,6 @@ export const MAX_KEY_SEGMENT_BYTES = 256;
  * digest of the raw value when the encoding exceeds
  * {@link MAX_KEY_SEGMENT_BYTES}. Deterministic, so key construction on the
  * write path and the continuation-lookup path always agree.
- *
- * Exported for the session ledger, which builds its `session/` and
- * `ledger/` keys with the same encoding rules.
  */
 export function keySegment(raw: string): string {
   const encoded = encodeURIComponent(raw);
@@ -163,8 +157,8 @@ function stringValue(value: unknown): string | undefined {
 }
 
 /**
- * Tolerant `SessionRecord` decoder. Extra fields (`auth`, `purpose`, ledger
- * extras, future keys) are ignored. Returns undefined when required list
+ * Tolerant `SessionRecord` decoder. Extra fields (`auth`, `purpose`,
+ * future keys) are ignored. Returns undefined when required list
  * fields are missing or the wrong type.
  */
 export function parseDurableSessionRecord(

package/src/storage.ts

@@ -7,9 +7,8 @@
  * only, and eval/A/B history stays in process memory.
  *
  * The sink is a plain key-value store — put/get/delete/list, no schema —
- * plus a conditional-write group ({@link StorageConfig.cas}, the substrate
- * for framework coordination; optional for plain storage, required by
- * coordination features). Implementing that small KV core is enough for
+ * plus a conditional-write group ({@link StorageConfig.cas}; optional).
+ * Implementing that small KV core is enough for
  * FULL functionality: eval-run and A/B history are derived over the core
  * when the optional dedicated tables ({@link StorageConfig.evals} and
  * {@link StorageConfig.abs}) are not authored — those groups exist as
@@ -178,10 +177,7 @@ export interface StorageABTable {
 /**
  * Conditional writes (CAS) — the coordination tier of the storage backend
  * contract. Plain storage works without it, so existing backends keep
- * working across a platform upgrade; framework coordination (the upcoming
- * session ledger — see `@cursor/july/kv` for the backend-agnostic
- * interface) requires it and fails at startup, with an actionable
- * message, when the backend lacks it. The built-in backends all include
+ * working across a platform upgrade. The built-in backends all include
  * it, so implementing this group yourself only comes up for BYO storage.
  *
  * Grouped under {@link StorageConfig.cas} rather than as loose methods —
@@ -243,10 +239,8 @@ export interface StorageConfig {
   abs?: StorageABTable;
   /**
    * Conditional writes (CAS). Optional for plain storage — existing
-   * backends keep working without it — but required by coordination
-   * features (the session ledger), which fail fast when it is absent.
-   * The built-in backends (`fileKv`, `cursorHostedStorage`) both include
-   * it. See {@link StorageCasTable}.
+   * backends keep working without it. The built-in backends (`fileKv`,
+   * `cursorHostedStorage`) both include it. See {@link StorageCasTable}.
    */
   cas?: StorageCasTable;
   /**
@@ -321,7 +315,7 @@ export function defineStorage(config: StorageConfig): StorageDefinition {
     ] as const;
     const cas = config.cas;
     // A partial group is a bug, not a legacy config: half-implemented CAS
-    // would pass the capability probe and corrupt coordination.
+    // would pass the capability probe.
     const missingCasHooks = casHooks.filter(
       (hook) => typeof cas[hook] !== "function"
     );