@cursor/july 0.1.43 → 0.1.46

package/src/internal/session-engine.ts

@@ -10,6 +10,7 @@
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { SDKCustomTool, SDKCustomToolResult } from "@cursor/sdk";
+import type { Meter } from "@opentelemetry/api";
 import {
   type ABDefinition,
   mergeABInstructions,
@@ -75,7 +76,7 @@ import { foldABStream } from "./ab-fold.js";
 import { type ABSnapshot, buildABSnapshot } from "./ab-snapshot.js";
 import { ApprovalGate } from "./approval-gate.js";
 import { ArtifactsStore } from "./artifacts-store.js";
-import { samePrincipal } from "./auth.js";
+import { SessionAuthError, samePrincipal } from "./auth.js";
 import { mergeCloudOptions, resolveSessionRuntime } from "./cloud-merge.js";
 import {
   applyCloudUsageToEvents,
@@ -95,6 +96,7 @@ import { TurnEventMapper } from "./event-mapper.js";
 import { selectFrameworkStorageDefinition } from "./framework-storage-selection.js";
 import { createHostFilesApi } from "./host-files.js";
 import { createHostKvApi } from "./host-kv.js";
+import { createHostOtelApi, type HostOtelSessionApi } from "./host-otel.js";
 import {
   createHostPlatforms,
   createHostSlackClient,
@@ -147,14 +149,9 @@ export class SessionBusyError extends Error {
   }
 }
 
-export class SessionAuthError extends Error {
-  constructor(sessionId: string) {
-    super(
-      `Session ${sessionId} belongs to a different principal; pass the original caller auth on follow-up`
-    );
-    this.name = "SessionAuthError";
-  }
-}
+// Defined in auth.js (the ledger pump needs it without importing this
+// module); re-exported here because this is its historical public home.
+export { SessionAuthError } from "./auth.js";
 
 export class UnknownChannelError extends Error {
   constructor(channelId: string) {
@@ -232,10 +229,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
@@ -246,6 +244,8 @@ export interface SessionEngineOptions {
   durableSessionStore?: HostKvApi;
   /** Process-level OTel collector; observe-only, never fatal. */
   otel?: OtelCollector;
+  /** Process-level meter for {@link HostContext.otel}. Absent → no-op counters. */
+  otelMeter?: Meter;
 }
 
 /**
@@ -282,12 +282,13 @@ interface ActiveToolContext {
 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;
 }
 
 interface CoalescedQueuedTurn {
@@ -362,6 +363,7 @@ export class SessionEngine {
   private readonly approvals = new ApprovalGate();
   private readonly abCollector: ABCollector;
   private readonly otel: OtelCollector | undefined;
+  private readonly otelHost: HostOtelSessionApi;
   private reminderApi: HostContext["reminders"];
   private evalsApi: HostContext["evals"];
   private readonly kvApi: HostContext["kv"];
@@ -395,6 +397,11 @@ export class SessionEngine {
     this.getCloudUsage = options.getCloudUsage ?? defaultGetCloudUsage;
     this.estimateTurnCost = options.estimateTurnCost ?? estimateTurnCostFromApi;
     this.otel = options.otel;
+    this.otelHost = createHostOtelApi({
+      agentName: options.project.name,
+      meter: options.otelMeter,
+      collector: options.otel,
+    });
     this.turnGovernor = new TurnGovernor(options.project.agent.concurrency);
     this.sessions = new SessionStore(join(options.stateRoot, "sessions"));
     this.nudgeStore = new SlackNudgeStore(
@@ -472,11 +479,12 @@ export class SessionEngine {
       this.channelsById.set(channel.id, channel.definition);
     }
     this.ledgerServing = this.buildLedgerServing(options);
+    this.ledgerServing?.start();
   }
 
   /**
    * 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(
@@ -485,15 +493,46 @@ export class SessionEngine {
     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: (request) =>
-        this.send(request.channelId, request.message, {
-          ...request.options,
-          continuationToken: request.continuationToken,
-          ledgerDelivery: true,
+      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,
     });
   }
@@ -511,13 +550,14 @@ export 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(
     options: SessionEngineOptions
@@ -527,7 +567,7 @@ export class SessionEngine {
     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). Provide a store implementing those methods (see @cursor/july/kv).`
+          `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);
@@ -574,7 +614,7 @@ export class SessionEngine {
     this.cloudServerToolsConnection = connection;
   }
 
-  /** Shared host services (MCP / GitHub / Slack / reminders / evals / kv / Slack nudges). */
+  /** Shared host services (MCP / GitHub / Slack / reminders / evals / kv / files / otel / Slack nudges). */
   get host(): HostContext {
     return {
       mcp: this.mcpHost,
@@ -584,6 +624,7 @@ export class SessionEngine {
       evals: this.evalsApi,
       kv: this.kvApi,
       files: this.filesApi,
+      otel: this.otelHost,
       slackNudges: this.slackNudgeHostApi(),
     };
   }
@@ -598,7 +639,11 @@ export class SessionEngine {
     const host = this.host;
     return sessionId === undefined
       ? host
-      : { ...host, files: this.filesApi.forSession(sessionId) };
+      : {
+          ...host,
+          files: this.filesApi.forSession(sessionId),
+          otel: this.otelHost.forSession(sessionId),
+        };
   }
 
   /** Unbound `ctx.artifacts` facade (channel handlers, scratch tool calls). */
@@ -714,10 +759,10 @@ export class SessionEngine {
     message: string,
     options: EngineSendOptions = {}
   ): Promise<ChannelSession> {
-    // Ledger-mode agents acquire the session lease before any turn runs;
-    // only the seam's own lease-holding deliveries fall through to the
-    // resident path.
-    if (this.ledgerServing !== undefined && options.ledgerDelivery !== true) {
+    // 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;
@@ -791,13 +836,20 @@ export class SessionEngine {
           ),
         }));
       }
+      const since = (await this.logs.get(record.sessionId)).count;
       const coalesced = await this.startTurn(record.sessionId, message, {
         admission: options.admission ?? "preempt",
         ...(options.coalesceSourceTs === undefined
           ? {}
           : { sourceTs: options.coalesceSourceTs }),
       });
-      return this.channelSession(record.sessionId, record, false, coalesced);
+      return this.channelSession(
+        record.sessionId,
+        record,
+        false,
+        coalesced,
+        since
+      );
     }
 
     const now = new Date().toISOString();
@@ -823,18 +875,26 @@ 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 },
     });
     record = await this.enrollABs(record);
+    const since = (await this.logs.get(record.sessionId)).count;
     await this.startTurn(record.sessionId, message, {
       admission: options.admission ?? "preempt",
       ...(options.coalesceSourceTs === undefined
         ? {}
         : { sourceTs: options.coalesceSourceTs }),
     });
-    return this.channelSession(record.sessionId, record, true, false);
+    return this.channelSession(record.sessionId, record, true, false, since);
   }
 
   /** Whether a continuation token already maps to a session on this channel. */
@@ -1359,6 +1419,9 @@ export class SessionEngine {
         workspaceDir,
         runnerStateDir: join(this.stateRoot, "runner"),
         sandbox: agent.local?.sandbox === true,
+        ...(agent.allowedTools === undefined
+          ? {}
+          : { tools: agent.allowedTools }),
         mcpServers: this.buildMcpServers("local"),
         subagents: buildRunnerSubagents(agent),
         ...(agent.model === undefined ? {} : { model: agent.model }),
@@ -1614,6 +1677,15 @@ export class SessionEngine {
       agentRuntime: agent.runtime,
       cloudOverride: record.cloudOverride,
     });
+    // Fail closed: the SDK cannot enforce the built-in tool allowlist on
+    // cloud agents yet, and a restriction that silently does not apply is
+    // worse than a refused turn. Cloud-runtime agents already fail
+    // discovery; this guards hybrid agents' per-send cloud sessions.
+    if (runtime === "cloud" && agent.allowedTools !== undefined) {
+      throw new Error(
+        `Agent "${agent.name}" declares a built-in tool allowlist (tools), which cannot be enforced on cloud turns yet. Refusing the cloud session rather than running it unrestricted.`
+      );
+    }
     const mergedCloud =
       runtime === "cloud"
         ? mergeCloudOptions({
@@ -1668,6 +1740,9 @@ export class SessionEngine {
         : { sdkAgentId: record.sdkAgentId }),
       workspaceDir: this.harnessCwd(record),
       sandbox: this.project.agent.local?.sandbox === true,
+      ...(runtime === "local" && agent.allowedTools !== undefined
+        ? { tools: agent.allowedTools }
+        : {}),
       runnerStateDir: join(this.stateRoot, "runner"),
       prompt: turnPrompt,
       isFirstTurn,
@@ -1996,6 +2071,7 @@ export class SessionEngine {
         }),
       getSession: (channelId, sessionId) =>
         this.getChannelSession(channelId, sessionId),
+      emit: args.emit,
     };
     try {
       const needsGate = await evaluateNeedsApproval(
@@ -2284,6 +2360,16 @@ export class SessionEngine {
     this.logger(`[session] tool ${toolName} start (direct ${callId})`);
     let result: unknown;
     let isError: boolean;
+    const live = record;
+    const emit =
+      live === undefined
+        ? undefined
+        : (payload: SessionEventPayload) => {
+            void this.appendEvent(live.sessionId, {
+              ...payload,
+              turnId: callId,
+            }).catch(() => {});
+          };
     try {
       result = normalizeToolResult(
         await execute(validation.value as never, {
@@ -2310,6 +2396,7 @@ export class SessionEngine {
             }),
           getSession: (channelId, sessionId) =>
             this.getChannelSession(channelId, sessionId),
+          emit,
         })
       );
       isError = isErrorEnvelope(result);
@@ -3009,7 +3096,8 @@ export class SessionEngine {
     sessionId: string,
     record: SessionRecord,
     isNew: boolean,
-    coalesced = false
+    coalesced = false,
+    since = 0
   ): ChannelSession {
     return {
       id: sessionId,
@@ -3018,7 +3106,7 @@ export class SessionEngine {
       ...(coalesced ? { coalesced: true } : {}),
       info: this.sessionInfo(record),
       getEventStream: (options?: { startIndex?: number }) =>
-        this.eventStream(sessionId, options?.startIndex ?? 0),
+        this.eventStream(sessionId, options?.startIndex ?? since),
       waitForCompletion: () => this.waitForCompletion(sessionId),
       setContinuationToken: (token: string | null) =>
         this.setContinuationToken(sessionId, token),

package/src/kv/memory-kv.ts

@@ -86,6 +86,14 @@ 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/ledger/janitor.ts

@@ -0,0 +1,193 @@
+/**
+ * The ledger janitor: lazy crash recovery has a hole — a session with
+ * pending events and no future events would wait forever — so serving runs
+ * this loop. It scans `ledger/` by prefix, finds pending-with-expired-lease
+ * sessions, claims them, and hands each claim to the execution callback.
+ * Self-host runs the same loop; it is part of the library, not the control
+ * plane.
+ *
+ * Nothing starts on construction: call `start()` for the interval loop or
+ * `runOnce()` for an explicit pass (what unit tests use).
+ */
+
+import type {
+  ClaimResult,
+  LedgerLease,
+  SessionLedger,
+} from "./session-ledger.js";
+
+export const DEFAULT_JANITOR_INTERVAL_MS = 15_000;
+
+export interface JanitorClaimedSession {
+  sessionId: string;
+  lease: LedgerLease;
+  head: number;
+  pending: string[];
+}
+
+export interface JanitorRunResult {
+  /** Ledgers scanned this pass. */
+  scanned: number;
+  /** Sessions this pass claimed and handed to the callback. */
+  claimed: JanitorClaimedSession[];
+  /** Orphan blob ids deleted (only when the sweep is enabled). */
+  orphansDeleted: string[];
+}
+
+export interface LedgerJanitorOptions {
+  ledger: SessionLedger;
+  /**
+   * Executes a recovered session: drain, run the turn, commit. Awaited so
+   * one pass never claims more sessions than it can serve.
+   */
+  onSession: (session: JanitorClaimedSession) => Promise<void> | void;
+  /** Scan cadence for `start()` (default {@link DEFAULT_JANITOR_INTERVAL_MS}). */
+  intervalMs?: number;
+  /**
+   * Also sweep unreferenced mailbox blobs each pass. Off by default —
+   * enable with `{ olderThanMs }` (see `SessionLedger.sweepOrphans`).
+   */
+  orphanSweep?: { olderThanMs?: number };
+  /** Called with per-session or sweep failures; the pass continues. */
+  onError?: (error: unknown, sessionId?: string) => void;
+  /** Time source for lease-expiry checks (default `Date.now`). */
+  clock?: () => number;
+}
+
+export interface LedgerJanitor {
+  start(): void;
+  /**
+   * Clear the interval AND await any in-flight pass: a running pass can
+   * claim a session and spawn a turn, so shutdown must not proceed while
+   * one is mid-scan.
+   */
+  stop(): Promise<void>;
+  runOnce(): Promise<JanitorRunResult>;
+}
+
+export function createLedgerJanitor(
+  options: LedgerJanitorOptions
+): LedgerJanitor {
+  const intervalMs = options.intervalMs ?? DEFAULT_JANITOR_INTERVAL_MS;
+  const clock = options.clock ?? Date.now;
+  const reportError =
+    options.onError ??
+    ((): void => {
+      // Recovery is best-effort per pass; an unobserved failure is retried
+      // on the next scan.
+    });
+
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let running = false;
+  /** The settled-shape promise of the pass currently scanning, if any. */
+  let inFlight: Promise<void> | undefined;
+
+  const runPass = async (): Promise<JanitorRunResult> => {
+    // An unparseable ledger record is reported and skipped: it degrades
+    // that one session's recovery, never the whole agent's pass.
+    const ledgers = await options.ledger.listLedgers((key, error) => {
+      reportError(
+        new Error(
+          `janitor scan: skipping unparseable ledger record at ${key}: ${String(
+            error instanceof Error ? error.message : error
+          )}`
+        )
+      );
+    });
+    const claimed: JanitorClaimedSession[] = [];
+    for (const snapshot of ledgers) {
+      if (snapshot.pending.length === 0) {
+        continue;
+      }
+      if (snapshot.lease !== null && snapshot.lease.expiresAt > clock()) {
+        continue;
+      }
+      let claim: ClaimResult;
+      try {
+        claim = await options.ledger.claim(snapshot.sessionId);
+      } catch (error) {
+        reportError(error, snapshot.sessionId);
+        continue;
+      }
+      if (!claim.claimed) {
+        continue;
+      }
+      const session: JanitorClaimedSession = {
+        sessionId: snapshot.sessionId,
+        lease: claim.lease,
+        head: claim.head,
+        pending: claim.pending,
+      };
+      claimed.push(session);
+      try {
+        await options.onSession(session);
+      } catch (error) {
+        reportError(error, snapshot.sessionId);
+      }
+    }
+
+    let orphansDeleted: string[] = [];
+    if (options.orphanSweep !== undefined) {
+      try {
+        const swept = await options.ledger.sweepOrphans({
+          olderThanMs: options.orphanSweep.olderThanMs,
+        });
+        orphansDeleted = swept.deleted;
+      } catch (error) {
+        reportError(error);
+      }
+    }
+    return { scanned: ledgers.length, claimed, orphansDeleted };
+  };
+
+  const runOnce = (): Promise<JanitorRunResult> => {
+    const pass = runPass();
+    const settled = pass.then(
+      () => undefined,
+      () => undefined
+    );
+    inFlight = settled;
+    void settled.finally(() => {
+      if (inFlight === settled) {
+        inFlight = undefined;
+      }
+    });
+    return pass;
+  };
+
+  const tick = async (): Promise<void> => {
+    // Skip a tick rather than overlap passes when a scan outlasts the
+    // cadence — overlapping claims would just fence each other.
+    if (running) {
+      return;
+    }
+    running = true;
+    try {
+      await runOnce();
+    } catch (error) {
+      reportError(error);
+    } finally {
+      running = false;
+    }
+  };
+
+  return {
+    start(): void {
+      if (timer !== undefined) {
+        return;
+      }
+      timer = setInterval(() => {
+        void tick();
+      }, intervalMs);
+      timer.unref?.();
+    },
+    async stop(): Promise<void> {
+      if (timer !== undefined) {
+        clearInterval(timer);
+        timer = undefined;
+      }
+      await inFlight;
+    },
+    runOnce,
+  };
+}