@cursor/july 0.1.43 → 0.1.46

package/dist/internal/session-engine.js

@@ -30,7 +30,7 @@ import { foldABStream } from "./ab-fold.js";
 import { 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, cloudSdkAgentIdFromEvents, isUnpricedCompletedTurn, mapSdkTokenUsage, } from "./cloud-turn-cost.js";
 import { isDevMode } from "./dev-mode.js";
@@ -40,6 +40,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 } from "./host-otel.js";
 import { createHostPlatforms, createHostSlackClient, } from "./host-platforms.js";
 import { formatContinuationToken, newContinuationKey, newSessionId, newToolCallId, } from "./ids.js";
 import { validateToolInput } from "./json-schema.js";
@@ -61,12 +62,9 @@ export class SessionBusyError extends Error {
         this.name = "SessionBusyError";
     }
 }
-export class SessionAuthError extends Error {
-    constructor(sessionId) {
-        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) {
         super(`Unknown channel "${channelId}"`);
@@ -112,7 +110,8 @@ export class ApprovalInterruptedError extends Error {
 }
 export class SessionEngine {
     constructor(options) {
-        var _a, _b, _c, _d;
+        var _a;
+        var _b, _c, _d, _e;
         /** In-flight lazy restores, deduped per channel + continuation key. */
         this.restoreInFlight = new Map();
         this.channelsById = new Map();
@@ -149,10 +148,15 @@ export class SessionEngine {
         this.project = options.project;
         this.stateRoot = options.stateRoot;
         this.runner = options.runner;
-        this.logger = (_a = options.logger) !== null && _a !== void 0 ? _a : (() => { });
-        this.getCloudUsage = (_b = options.getCloudUsage) !== null && _b !== void 0 ? _b : defaultGetCloudUsage;
-        this.estimateTurnCost = (_c = options.estimateTurnCost) !== null && _c !== void 0 ? _c : estimateTurnCostFromApi;
+        this.logger = (_b = options.logger) !== null && _b !== void 0 ? _b : (() => { });
+        this.getCloudUsage = (_c = options.getCloudUsage) !== null && _c !== void 0 ? _c : defaultGetCloudUsage;
+        this.estimateTurnCost = (_d = options.estimateTurnCost) !== null && _d !== void 0 ? _d : 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(join(options.stateRoot, "slack-nudges"));
@@ -190,7 +194,7 @@ export class SessionEngine {
         // resolves them; the host-side MCP registry starts with the concrete
         // connections and gains the rest via setResolvedConnections.
         this.mcpHost = new McpHost(options.project.agent.connections.filter((connection) => !isSymbolicConnectionTransport(connection.transport)));
-        const basePlatforms = (_d = options.platforms) !== null && _d !== void 0 ? _d : createHostPlatforms();
+        const basePlatforms = (_e = options.platforms) !== null && _e !== void 0 ? _e : createHostPlatforms();
         const slackBinding = resolveDedicatedSlackHostBinding(options.project.channels);
         this.platforms =
             slackBinding === undefined
@@ -206,20 +210,37 @@ export class SessionEngine {
             this.channelsById.set(channel.id, channel.definition);
         }
         this.ledgerServing = this.buildLedgerServing(options);
+        (_a = this.ledgerServing) === null || _a === void 0 ? void 0 : _a.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.
      */
     buildLedgerServing(options) {
         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, Object.assign(Object.assign({}, request.options), { continuationToken: request.continuationToken, ledgerDelivery: true })),
+            deliverTurn: (envelope) => this.send(envelope.channelId, envelope.message, Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ 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 })), (envelope.workspaceDir === undefined
+                ? {}
+                : { workspaceDir: envelope.workspaceDir })), (envelope.cloud === undefined ? {} : { cloud: envelope.cloud })), { fromLedgerPump: true })),
+            findSession: (channelId, continuationToken) => __awaiter(this, void 0, void 0, function* () {
+                let record = yield this.sessions.findByContinuation(channelId, continuationToken);
+                if (record === undefined) {
+                    record = yield this.restoreSessionByContinuation(channelId, continuationToken);
+                }
+                return record === undefined
+                    ? undefined
+                    : this.channelSession(record.sessionId, record, false);
+            }),
             logger: this.logger,
         });
     }
@@ -236,20 +257,21 @@ 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.
      */
     resolveDurableSessionStore(options) {
         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). Provide a store implementing those methods (see @cursor/july/kv).`);
+                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);
         }
@@ -287,7 +309,7 @@ export class SessionEngine {
     setCloudServerToolsConnection(connection) {
         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() {
         return {
             mcp: this.mcpHost,
@@ -297,6 +319,7 @@ export class SessionEngine {
             evals: this.evalsApi,
             kv: this.kvApi,
             files: this.filesApi,
+            otel: this.otelHost,
             slackNudges: this.slackNudgeHostApi(),
         };
     }
@@ -310,7 +333,7 @@ export class SessionEngine {
         const host = this.host;
         return sessionId === undefined
             ? host
-            : Object.assign(Object.assign({}, host), { files: this.filesApi.forSession(sessionId) });
+            : Object.assign(Object.assign({}, host), { files: this.filesApi.forSession(sessionId), otel: this.otelHost.forSession(sessionId) });
     }
     /** Unbound `ctx.artifacts` facade (channel handlers, scratch tool calls). */
     get artifacts() {
@@ -404,10 +427,10 @@ export class SessionEngine {
         return __awaiter(this, arguments, void 0, function* (channelId, message, options = {}) {
             var _a;
             var _b, _c, _d, _e, _f;
-            // 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 = (_b = options.auth) !== null && _b !== void 0 ? _b : null;
@@ -448,10 +471,11 @@ export class SessionEngine {
                 if (options.refreshState !== undefined) {
                     record = yield this.updateRecord(record.sessionId, (current) => (Object.assign(Object.assign({}, current), { channelState: mergeChannelStateSkipNull(current.channelState, options.refreshState) })));
                 }
+                const since = (yield this.logs.get(record.sessionId)).count;
                 const coalesced = yield this.startTurn(record.sessionId, message, Object.assign({ admission: (_c = options.admission) !== null && _c !== void 0 ? _c : "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();
             const channelState = this.initialChannelState(channelId, options.state);
@@ -476,15 +500,23 @@ export class SessionEngine {
             };
             yield this.sessions.save(record);
             (_a = this.storage) === null || _a === void 0 ? void 0 : _a.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);
+                yield this.storage.whenIdle();
+            }
             yield this.appendEvent(record.sessionId, {
                 type: "session.started",
                 data: { channelId },
             });
             record = yield this.enrollABs(record);
+            const since = (yield this.logs.get(record.sessionId)).count;
             yield this.startTurn(record.sessionId, message, Object.assign({ admission: (_f = options.admission) !== null && _f !== void 0 ? _f : "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. */
@@ -914,7 +946,9 @@ export class SessionEngine {
             }
             const startedAt = Date.now();
             try {
-                const outcome = yield this.runner.prewarm(Object.assign({ workspaceDir, runnerStateDir: join(this.stateRoot, "runner"), sandbox: ((_b = agent.local) === null || _b === void 0 ? void 0 : _b.sandbox) === true, mcpServers: this.buildMcpServers("local"), subagents: buildRunnerSubagents(agent) }, (agent.model === undefined ? {} : { model: agent.model })));
+                const outcome = yield this.runner.prewarm(Object.assign(Object.assign(Object.assign({ workspaceDir, runnerStateDir: join(this.stateRoot, "runner"), sandbox: ((_b = agent.local) === null || _b === void 0 ? void 0 : _b.sandbox) === true }, (agent.allowedTools === undefined
+                    ? {}
+                    : { tools: agent.allowedTools })), { mcpServers: this.buildMcpServers("local"), subagents: buildRunnerSubagents(agent) }), (agent.model === undefined ? {} : { model: agent.model })));
                 // Report what happened rather than that the call returned: a runner
                 // that cannot warm resolves cleanly, and logging success there would
                 // tell an operator the workspace is hot when nothing touched it.
@@ -1107,6 +1141,13 @@ 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({
                 base: agent.cloud,
@@ -1153,9 +1194,11 @@ export class SessionEngine {
                 turnPrompt = `${preamble}\n\n${turnPrompt}`;
             }
         }
-        return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ sessionId: record.sessionId }, (record.sdkAgentId === undefined
+        return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ sessionId: record.sessionId }, (record.sdkAgentId === undefined
             ? {}
-            : { sdkAgentId: record.sdkAgentId })), { workspaceDir: this.harnessCwd(record), sandbox: ((_c = this.project.agent.local) === null || _c === void 0 ? void 0 : _c.sandbox) === true, runnerStateDir: join(this.stateRoot, "runner"), prompt: turnPrompt, isFirstTurn }), (images !== undefined && images.length > 0 ? { images } : {})), (agent.model === undefined ? {} : { model: agent.model })), { runtime }), (mergedCloud === undefined ? {} : { cloud: mergedCloud })), { customTools: runtime === "local" ? this.buildCustomTools(record, turnId, emit) : {}, mcpServers: this.buildMcpServers(runtime, record.sessionId), subagents: buildRunnerSubagents(agent), onUpdate,
+            : { sdkAgentId: record.sdkAgentId })), { workspaceDir: this.harnessCwd(record), sandbox: ((_c = this.project.agent.local) === null || _c === void 0 ? void 0 : _c.sandbox) === true }), (runtime === "local" && agent.allowedTools !== undefined
+            ? { tools: agent.allowedTools }
+            : {})), { runnerStateDir: join(this.stateRoot, "runner"), prompt: turnPrompt, isFirstTurn }), (images !== undefined && images.length > 0 ? { images } : {})), (agent.model === undefined ? {} : { model: agent.model })), { runtime }), (mergedCloud === undefined ? {} : { cloud: mergedCloud })), { customTools: runtime === "local" ? this.buildCustomTools(record, turnId, emit) : {}, mcpServers: this.buildMcpServers(runtime, record.sessionId), subagents: buildRunnerSubagents(agent), onUpdate,
             signal, 
             // Local follow-ups expire any lingering active run so a preempted turn
             // (or one orphaned by a crashed process) never blocks this send.
@@ -1398,6 +1441,7 @@ export class SessionEngine {
                 }),
                 send: (channelId, message, sendOptions = {}) => { var _a; return this.send(channelId, message, Object.assign(Object.assign({}, sendOptions), { auth: (_a = sendOptions.auth) !== null && _a !== void 0 ? _a : args.record.auth })); },
                 getSession: (channelId, sessionId) => this.getChannelSession(channelId, sessionId),
+                emit: args.emit,
             };
             try {
                 const needsGate = yield evaluateNeedsApproval(args.tool.definition.needsApproval, validation.value);
@@ -1622,6 +1666,12 @@ export class SessionEngine {
             this.logger(`[session] tool ${toolName} start (direct ${callId})`);
             let result;
             let isError;
+            const live = record;
+            const emit = live === undefined
+                ? undefined
+                : (payload) => {
+                    void this.appendEvent(live.sessionId, Object.assign(Object.assign({}, payload), { turnId: callId })).catch(() => { });
+                };
             try {
                 result = normalizeToolResult(yield execute(validation.value, {
                     toolCallId: callId,
@@ -1640,6 +1690,7 @@ export class SessionEngine {
                             ? sendOptions.auth
                             : session.auth })),
                     getSession: (channelId, sessionId) => this.getChannelSession(channelId, sessionId),
+                    emit,
                 }));
                 isError = isErrorEnvelope(result);
             }
@@ -2216,8 +2267,8 @@ export class SessionEngine {
             ? {}
             : { sdkAgentId: record.sdkAgentId }));
     }
-    channelSession(sessionId, record, isNew, coalesced = false) {
-        return Object.assign(Object.assign({ id: sessionId, continuationToken: record.continuationKey, isNew }, (coalesced ? { coalesced: true } : {})), { info: this.sessionInfo(record), getEventStream: (options) => { var _a; return this.eventStream(sessionId, (_a = options === null || options === void 0 ? void 0 : options.startIndex) !== null && _a !== void 0 ? _a : 0); }, waitForCompletion: () => this.waitForCompletion(sessionId), setContinuationToken: (token) => this.setContinuationToken(sessionId, token) });
+    channelSession(sessionId, record, isNew, coalesced = false, since = 0) {
+        return Object.assign(Object.assign({ id: sessionId, continuationToken: record.continuationKey, isNew }, (coalesced ? { coalesced: true } : {})), { info: this.sessionInfo(record), getEventStream: (options) => { var _a; return this.eventStream(sessionId, (_a = options === null || options === void 0 ? void 0 : options.startIndex) !== null && _a !== void 0 ? _a : since); }, waitForCompletion: () => this.waitForCompletion(sessionId), setContinuationToken: (token) => this.setContinuationToken(sessionId, token) });
     }
     resolveChannelId(channel) {
         if (typeof channel === "string") {

package/dist/kv/memory-kv.d.ts

@@ -18,6 +18,14 @@ export declare 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 declare function memoryCasTable(): StorageCasTable;
 //# sourceMappingURL=memory-kv.d.ts.map

package/dist/kv/memory-kv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-kv.d.ts","sourceRoot":"","sources":["../../src/kv/memory-kv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EACV,YAAY,EAIb,MAAM,aAAa,CAAC;AAErB,gDAAgD;AAChD,wBAAgB,cAAc,IAAI,YAAY,CA4D7C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,IAAI,eAAe,CAShD"}
+{"version":3,"file":"memory-kv.d.ts","sourceRoot":"","sources":["../../src/kv/memory-kv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EACV,YAAY,EAIb,MAAM,aAAa,CAAC;AAErB,gDAAgD;AAChD,wBAAgB,cAAc,IAAI,YAAY,CA4D7C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,IAAI,eAAe,CAShD"}

package/dist/kv/memory-kv.js

@@ -91,6 +91,14 @@ export function createMemoryKv() {
  * 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() {
     const kv = createMemoryKv();

package/dist/ledger/janitor.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 { LedgerLease, SessionLedger } from "./session-ledger.js";
+export declare const DEFAULT_JANITOR_INTERVAL_MS = 15000;
+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 declare function createLedgerJanitor(options: LedgerJanitorOptions): LedgerJanitor;
+//# sourceMappingURL=janitor.d.ts.map

package/dist/ledger/janitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"janitor.d.ts","sourceRoot":"","sources":["../../src/ledger/janitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAEV,WAAW,EACX,aAAa,EACd,MAAM,qBAAqB,CAAC;AAE7B,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAElD,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,gEAAgE;IAChE,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,aAAa,CAAC;IACtB;;;OAGG;IACH,SAAS,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpE,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,qEAAqE;IACrE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACvD,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,IAAI,IAAI,CAAC;IACd;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACtC;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,GAC5B,aAAa,CA2Hf"}

package/dist/ledger/janitor.js

@@ -0,0 +1,137 @@
+/**
+ * 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).
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+export const DEFAULT_JANITOR_INTERVAL_MS = 15000;
+export function createLedgerJanitor(options) {
+    var _a, _b, _c;
+    const intervalMs = (_a = options.intervalMs) !== null && _a !== void 0 ? _a : DEFAULT_JANITOR_INTERVAL_MS;
+    const clock = (_b = options.clock) !== null && _b !== void 0 ? _b : Date.now;
+    const reportError = (_c = options.onError) !== null && _c !== void 0 ? _c : (() => {
+        // Recovery is best-effort per pass; an unobserved failure is retried
+        // on the next scan.
+    });
+    let timer;
+    let running = false;
+    /** The settled-shape promise of the pass currently scanning, if any. */
+    let inFlight;
+    const runPass = () => __awaiter(this, void 0, void 0, function* () {
+        // An unparseable ledger record is reported and skipped: it degrades
+        // that one session's recovery, never the whole agent's pass.
+        const ledgers = yield 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 = [];
+        for (const snapshot of ledgers) {
+            if (snapshot.pending.length === 0) {
+                continue;
+            }
+            if (snapshot.lease !== null && snapshot.lease.expiresAt > clock()) {
+                continue;
+            }
+            let claim;
+            try {
+                claim = yield options.ledger.claim(snapshot.sessionId);
+            }
+            catch (error) {
+                reportError(error, snapshot.sessionId);
+                continue;
+            }
+            if (!claim.claimed) {
+                continue;
+            }
+            const session = {
+                sessionId: snapshot.sessionId,
+                lease: claim.lease,
+                head: claim.head,
+                pending: claim.pending,
+            };
+            claimed.push(session);
+            try {
+                yield options.onSession(session);
+            }
+            catch (error) {
+                reportError(error, snapshot.sessionId);
+            }
+        }
+        let orphansDeleted = [];
+        if (options.orphanSweep !== undefined) {
+            try {
+                const swept = yield options.ledger.sweepOrphans({
+                    olderThanMs: options.orphanSweep.olderThanMs,
+                });
+                orphansDeleted = swept.deleted;
+            }
+            catch (error) {
+                reportError(error);
+            }
+        }
+        return { scanned: ledgers.length, claimed, orphansDeleted };
+    });
+    const runOnce = () => {
+        const pass = runPass();
+        const settled = pass.then(() => undefined, () => undefined);
+        inFlight = settled;
+        void settled.finally(() => {
+            if (inFlight === settled) {
+                inFlight = undefined;
+            }
+        });
+        return pass;
+    };
+    const tick = () => __awaiter(this, void 0, void 0, function* () {
+        // 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 {
+            yield runOnce();
+        }
+        catch (error) {
+            reportError(error);
+        }
+        finally {
+            running = false;
+        }
+    });
+    return {
+        start() {
+            var _a;
+            if (timer !== undefined) {
+                return;
+            }
+            timer = setInterval(() => {
+                void tick();
+            }, intervalMs);
+            (_a = timer.unref) === null || _a === void 0 ? void 0 : _a.call(timer);
+        },
+        stop() {
+            return __awaiter(this, void 0, void 0, function* () {
+                if (timer !== undefined) {
+                    clearInterval(timer);
+                    timer = undefined;
+                }
+                yield inFlight;
+            });
+        },
+        runOnce,
+    };
+}