@cursor/july 0.1.45 → 0.1.46
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +4 -2
- package/README.md +3 -1
- package/dist/channels/github/api.d.ts +25 -0
- package/dist/channels/github/api.d.ts.map +1 -1
- package/dist/channels/github/api.js +48 -0
- package/dist/channels/github/cursor-account.d.ts +7 -0
- package/dist/channels/github/cursor-account.d.ts.map +1 -1
- package/dist/channels/github/cursor-account.js +18 -0
- package/dist/channels/github/defaults.d.ts +1 -1
- package/dist/channels/github/defaults.js +1 -1
- package/dist/channels/github/github-channel.d.ts.map +1 -1
- package/dist/channels/github/github-channel.js +2 -2
- package/dist/channels/github/progress.d.ts +6 -5
- package/dist/channels/github/progress.d.ts.map +1 -1
- package/dist/channels/github/progress.js +58 -16
- package/dist/channels/github/state.d.ts +11 -0
- package/dist/channels/github/state.d.ts.map +1 -1
- package/dist/channels/github/state.js +1 -1
- package/dist/channels/github/types.d.ts +3 -3
- package/dist/docs/404.html +2 -2
- package/dist/docs/ab.html +3 -3
- package/dist/docs/assets/{app.fHnNXEJ6.js → app.C2NFTb-h.js} +1 -1
- package/dist/docs/assets/chunks/@localSearchIndexroot.B-FxvuoI.js +1 -0
- package/dist/docs/assets/chunks/{VPLocalSearchBox.Cf6ghfFY.js → VPLocalSearchBox.o1_FJGip.js} +1 -1
- package/dist/docs/assets/chunks/{theme.B_5-VLe8.js → theme.BcGduE7g.js} +2 -2
- package/dist/docs/assets/{guides_github.md.DSg0j9qj.js → guides_github.md.B8QKtIpw.js} +7 -6
- package/dist/docs/assets/{guides_github.md.DSg0j9qj.lean.js → guides_github.md.B8QKtIpw.lean.js} +1 -1
- package/dist/docs/assets/{reference_agent-config.md.XRpxctsA.js → reference_agent-config.md.DHkkvcEZ.js} +4 -4
- package/dist/docs/assets/{reference_agent-config.md.XRpxctsA.lean.js → reference_agent-config.md.DHkkvcEZ.lean.js} +1 -1
- package/dist/docs/assets/{reference_hooks.md.4cbRRIIu.js → reference_hooks.md.DJE5DXcT.js} +1 -1
- package/dist/docs/assets/{storage.md.DcGSnIxX.js → storage.md.CJYd5YmN.js} +2 -2
- package/dist/docs/assets/{storage.md.DcGSnIxX.lean.js → storage.md.CJYd5YmN.lean.js} +1 -1
- package/dist/docs/building-with-agents.html +3 -3
- package/dist/docs/concepts.html +3 -3
- package/dist/docs/deployment.html +3 -3
- package/dist/docs/evals.html +3 -3
- package/dist/docs/example-agents/approval-buddy.html +3 -3
- package/dist/docs/example-agents/benny.html +3 -3
- package/dist/docs/example-agents/bugbot.html +3 -3
- package/dist/docs/example-agents/codebase-wiki.html +3 -3
- package/dist/docs/example-agents/codeowners-review.html +3 -3
- package/dist/docs/example-agents/concierge.html +3 -3
- package/dist/docs/example-agents/fsd.html +3 -3
- package/dist/docs/example-agents/index.html +3 -3
- package/dist/docs/example-agents/knowledge-base.html +3 -3
- package/dist/docs/example-agents/oncall.html +3 -3
- package/dist/docs/example-agents/security-reviewer.html +3 -3
- package/dist/docs/example-agents/slack-agent.html +3 -3
- package/dist/docs/example-agents/weather-agent.html +3 -3
- package/dist/docs/guides/agent-to-agent.html +3 -3
- package/dist/docs/guides/cloud-runtime.html +3 -3
- package/dist/docs/guides/github.html +10 -9
- package/dist/docs/guides/human-in-the-loop.html +3 -3
- package/dist/docs/guides/mcp-oauth.html +3 -3
- package/dist/docs/guides/opentelemetry.html +3 -3
- package/dist/docs/guides/slack.html +3 -3
- package/dist/docs/guides/webhooks.html +3 -3
- package/dist/docs/hashmap.json +1 -1
- package/dist/docs/hillclimbing.html +3 -3
- package/dist/docs/index.html +3 -3
- package/dist/docs/quickstart.html +3 -3
- package/dist/docs/reference/agent-config.html +6 -6
- package/dist/docs/reference/artifacts.html +3 -3
- package/dist/docs/reference/channels.html +3 -3
- package/dist/docs/reference/cli.html +3 -3
- package/dist/docs/reference/connections.html +3 -3
- package/dist/docs/reference/hooks.html +5 -5
- package/dist/docs/reference/http-api.html +3 -3
- package/dist/docs/reference/instructions.html +3 -3
- package/dist/docs/reference/playground.html +3 -3
- package/dist/docs/reference/project-layout.html +3 -3
- package/dist/docs/reference/prompt.html +3 -3
- package/dist/docs/reference/schedules.html +3 -3
- package/dist/docs/reference/sessions.html +3 -3
- package/dist/docs/reference/skills.html +3 -3
- package/dist/docs/reference/subagents.html +3 -3
- package/dist/docs/reference/tools.html +3 -3
- package/dist/docs/scaffolding-agents.html +3 -3
- package/dist/docs/storage.html +5 -5
- package/dist/docs/templates/triage.html +3 -3
- package/dist/docs/troubleshooting.html +3 -3
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/internal/auth.d.ts +4 -0
- package/dist/internal/auth.d.ts.map +1 -1
- package/dist/internal/auth.js +7 -0
- package/dist/internal/durable-session-store.d.ts +35 -23
- package/dist/internal/durable-session-store.d.ts.map +1 -1
- package/dist/internal/durable-session-store.js +71 -26
- package/dist/internal/ledger-serving.d.ts +135 -67
- package/dist/internal/ledger-serving.d.ts.map +1 -1
- package/dist/internal/ledger-serving.js +326 -107
- package/dist/internal/server.d.ts.map +1 -1
- package/dist/internal/server.js +2 -2
- package/dist/internal/session-engine.d.ts +18 -17
- package/dist/internal/session-engine.d.ts.map +1 -1
- package/dist/internal/session-engine.js +60 -27
- package/dist/kv/memory-kv.d.ts +8 -0
- package/dist/kv/memory-kv.d.ts.map +1 -1
- package/dist/kv/memory-kv.js +8 -0
- package/dist/ledger/janitor.d.ts +60 -0
- package/dist/ledger/janitor.d.ts.map +1 -0
- package/dist/ledger/janitor.js +137 -0
- package/dist/ledger/session-ledger.d.ts +132 -43
- package/dist/ledger/session-ledger.d.ts.map +1 -1
- package/dist/ledger/session-ledger.js +282 -50
- package/dist/ledger.d.ts +9 -8
- package/dist/ledger.d.ts.map +1 -1
- package/dist/ledger.js +7 -7
- package/dist/playground/assets/{index-Dces8BDp.js → index-6wW6SAc4.js} +32 -32
- package/dist/playground/assets/index-CSRYDAFw.css +1 -0
- package/dist/playground/index.html +2 -2
- package/dist/storage-backends/cursor-hosted.d.ts +5 -0
- package/dist/storage-backends/cursor-hosted.d.ts.map +1 -1
- package/dist/storage-backends/cursor-hosted.js +6 -0
- package/dist/types.d.ts +19 -8
- package/dist/types.d.ts.map +1 -1
- package/docs/guides/github.md +23 -18
- package/docs/reference/agent-config.md +31 -36
- package/docs/reference/hooks.md +1 -1
- package/docs/storage.md +26 -9
- package/package.json +1 -1
- package/src/channels/github/api.ts +122 -0
- package/src/channels/github/cursor-account.ts +23 -0
- package/src/channels/github/defaults.ts +1 -1
- package/src/channels/github/github-channel.ts +5 -1
- package/src/channels/github/progress.ts +84 -19
- package/src/channels/github/state.ts +14 -0
- package/src/channels/github/types.ts +3 -3
- package/src/index.ts +1 -0
- package/src/internal/auth.ts +10 -0
- package/src/internal/durable-session-store.ts +66 -27
- package/src/internal/ledger-serving.ts +439 -148
- package/src/internal/server.ts +6 -2
- package/src/internal/session-engine.ts +95 -37
- package/src/kv/memory-kv.ts +8 -0
- package/src/ledger/janitor.ts +193 -0
- package/src/ledger/session-ledger.ts +372 -68
- package/src/ledger.ts +21 -6
- package/src/storage-backends/cursor-hosted.ts +17 -2
- package/src/types.ts +19 -8
- package/dist/docs/assets/chunks/@localSearchIndexroot.BMT0xM4I.js +0 -1
- package/dist/playground/assets/index-CZH9EFvO.css +0 -1
- /package/dist/docs/assets/{reference_hooks.md.4cbRRIIu.lean.js → reference_hooks.md.DJE5DXcT.lean.js} +0 -0
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Session ledger — coordination
|
|
2
|
+
* Session ledger — KV coordination with a durable inbox.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
* agents never touch these keys directly:
|
|
4
|
+
* Three key families, all driven with `get` + CAS on a
|
|
5
|
+
* {@link SessionLedgerKv}; agents never touch these keys directly:
|
|
6
6
|
*
|
|
7
7
|
* ```
|
|
8
|
-
* session/<continuationKey>
|
|
9
|
-
* ledger/<sessionId>
|
|
8
|
+
* session/<continuationKey> identity, created with put-if-absent
|
|
9
|
+
* ledger/<sessionId> head + pending + lease — every mutation one CAS
|
|
10
|
+
* mailbox/<sessionId>/<eventId> immutable payload blobs, plain put
|
|
10
11
|
* ```
|
|
11
12
|
*
|
|
12
13
|
* The keys are deliberately bare: namespacing (per agent, per
|
|
@@ -15,21 +16,21 @@
|
|
|
15
16
|
* where it constructs the handle (see `durable-session-store.ts`), the
|
|
16
17
|
* same boundary where `host.kv` gets its agent scoping.
|
|
17
18
|
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
* *in-process* on the delivering pod; a crash loses that in-flight
|
|
24
|
-
* event exactly as resident serving does. What ledger mode adds over
|
|
25
|
-
* resident is cross-pod mutual exclusion, zombie fencing, and the
|
|
26
|
-
* committed head sequence. A dead pod needs no janitor: its lease
|
|
27
|
-
* simply expires (~30s) and the next delivery claims at generation+1.
|
|
19
|
+
* The guarantee: **exactly-once ledger apply, at-least-once actuation.**
|
|
20
|
+
* A commit is one CAS carrying the read version, the expected `head`, and
|
|
21
|
+
* the holder's `generation` — one committed transition per turn, atomic by
|
|
22
|
+
* construction. What the CAS cannot fence (a zombie's plain `host.kv`
|
|
23
|
+
* writes, external tool calls) is a stated bound, not this module's job.
|
|
28
24
|
*
|
|
29
|
-
* The
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
25
|
+
* The inbox makes events durable before their turn runs: `appendEvent`
|
|
26
|
+
* writes the payload blob, then one CAS indexes the eventId into
|
|
27
|
+
* `pending` — that CAS is the ack point. A delivery that finds the lease
|
|
28
|
+
* held walks away; the holder's commit sees the appended id in the same
|
|
29
|
+
* CAS value, keeps the lease, and drains again. Sessions whose holder
|
|
30
|
+
* died with events pending are recovered by the janitor
|
|
31
|
+
* (`./janitor.js`), which is also why the store must implement
|
|
32
|
+
* `listKeys`: the inbox brings the prefix scans (janitor + orphan
|
|
33
|
+
* sweep) that the coordination-only ledger did not need.
|
|
33
34
|
*
|
|
34
35
|
* Clocks: lease expiry compares `expiresAt` against {@link
|
|
35
36
|
* SessionLedgerOptions.clock} (default `Date.now`). Self-hosted N-pod
|
|
@@ -37,15 +38,19 @@
|
|
|
37
38
|
* backend-clock primitive can replace the default without touching the
|
|
38
39
|
* protocol code.
|
|
39
40
|
*/
|
|
40
|
-
import type { HostKvCasApi } from "../types.js";
|
|
41
|
+
import type { HostKvCasApi, JsonValue } from "../types.js";
|
|
41
42
|
export declare const LEASE_TTL_MS = 30000;
|
|
42
43
|
export declare const HEARTBEAT_INTERVAL_MS = 10000;
|
|
44
|
+
/** Unreferenced mailbox blobs older than this are sweepable. */
|
|
45
|
+
export declare const DEFAULT_ORPHAN_TTL_MS: number;
|
|
43
46
|
/**
|
|
44
|
-
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
+
* The KV surface the ledger uses — the full CAS-capable contract. The
|
|
48
|
+
* coordination half needs only `getWithVersion` / `putIfAbsent` /
|
|
49
|
+
* `putIfVersion`; the inbox adds plain `get`/`put`/`delete` for mailbox
|
|
50
|
+
* payload blobs and `listKeys` for the janitor scan and the orphan
|
|
51
|
+
* sweep.
|
|
47
52
|
*/
|
|
48
|
-
export type SessionLedgerKv =
|
|
53
|
+
export type SessionLedgerKv = HostKvCasApi;
|
|
49
54
|
/** Runtime probe for {@link SessionLedgerKv} on stores of unknown shape. */
|
|
50
55
|
export declare function supportsSessionLedgerKv(kv: object): kv is SessionLedgerKv;
|
|
51
56
|
/** `session/<continuationKey>` value. Immutable after creation. */
|
|
@@ -60,20 +65,39 @@ export interface LedgerLease {
|
|
|
60
65
|
expiresAt: number;
|
|
61
66
|
}
|
|
62
67
|
/**
|
|
63
|
-
* `ledger/<sessionId>` value: `{ sessionId, head,
|
|
64
|
-
* lastCommitId }`. `sessionId` lets
|
|
65
|
-
* without inverting digested key segments;
|
|
66
|
-
* acquisition counter that must survive
|
|
67
|
-
* cleanly released lease could reuse
|
|
68
|
-
* the ambiguous-commit recovery
|
|
68
|
+
* `ledger/<sessionId>` value: `{ sessionId, head, pending, lease,
|
|
69
|
+
* generation, lastCommitId }`. `sessionId` lets the janitor's prefix
|
|
70
|
+
* scan address sessions without inverting digested key segments;
|
|
71
|
+
* `generation` is a monotonic acquisition counter that must survive
|
|
72
|
+
* lease release, or a zombie of a cleanly released lease could reuse
|
|
73
|
+
* its generation; `lastCommitId` is the ambiguous-commit recovery
|
|
74
|
+
* token.
|
|
69
75
|
*/
|
|
70
76
|
export interface LedgerSnapshot {
|
|
71
77
|
sessionId: string;
|
|
72
78
|
head: number;
|
|
79
|
+
pending: string[];
|
|
73
80
|
lease: LedgerLease | null;
|
|
74
81
|
generation: number;
|
|
75
82
|
lastCommitId: string | null;
|
|
76
83
|
}
|
|
84
|
+
/** One event handed to {@link SessionLedger.appendEvent}. */
|
|
85
|
+
export interface LedgerEventInput {
|
|
86
|
+
eventId: string;
|
|
87
|
+
envelope: JsonValue;
|
|
88
|
+
hookContext?: JsonValue;
|
|
89
|
+
/** Source-assigned timestamp used for drain ordering. */
|
|
90
|
+
sourceTs: number;
|
|
91
|
+
}
|
|
92
|
+
/** One drained mailbox event. */
|
|
93
|
+
export interface LedgerEvent {
|
|
94
|
+
eventId: string;
|
|
95
|
+
envelope: JsonValue;
|
|
96
|
+
hookContext: JsonValue | null;
|
|
97
|
+
sourceTs: number;
|
|
98
|
+
/** Pod-clock write time; drives the orphan sweep TTL. */
|
|
99
|
+
storedAt: number;
|
|
100
|
+
}
|
|
77
101
|
export type EnsureSessionResult = {
|
|
78
102
|
created: boolean;
|
|
79
103
|
session: SessionIdentity;
|
|
@@ -82,6 +106,7 @@ export type ClaimResult = {
|
|
|
82
106
|
claimed: true;
|
|
83
107
|
lease: LedgerLease;
|
|
84
108
|
head: number;
|
|
109
|
+
pending: string[];
|
|
85
110
|
} | {
|
|
86
111
|
claimed: false;
|
|
87
112
|
reason: "held";
|
|
@@ -95,27 +120,45 @@ export type HeartbeatResult = {
|
|
|
95
120
|
ok: false;
|
|
96
121
|
reason: "not-found" | "fenced";
|
|
97
122
|
};
|
|
123
|
+
export interface DrainResult {
|
|
124
|
+
/** `head` at read time — pass as `expectedHead` to the matching commit. */
|
|
125
|
+
head: number;
|
|
126
|
+
/** Pending events sorted by `sourceTs`, then `eventId`. */
|
|
127
|
+
events: LedgerEvent[];
|
|
128
|
+
}
|
|
98
129
|
export interface CommitArgs {
|
|
130
|
+
/** Event ids this turn actually consumed. Only these leave `pending`. */
|
|
131
|
+
drainedEventIds: string[];
|
|
99
132
|
/** The holder's lease generation (fences zombies). */
|
|
100
133
|
generation: number;
|
|
101
|
-
/** `head` observed at
|
|
134
|
+
/** `head` observed at drain time (fences concurrent turns). */
|
|
102
135
|
expectedHead: number;
|
|
103
136
|
/** Unique per commit attempt; enables ambiguous-outcome recovery. */
|
|
104
137
|
commitId: string;
|
|
105
138
|
}
|
|
106
139
|
export interface CommitResult {
|
|
107
140
|
head: number;
|
|
141
|
+
/** Events that arrived mid-turn; non-empty ⇒ the lease was kept. */
|
|
142
|
+
pending: string[];
|
|
108
143
|
/**
|
|
109
144
|
* Whether this holder's lease is gone — for the caller's purposes, not
|
|
110
145
|
* the record's: `true` also when the re-read of an ambiguous commit
|
|
111
146
|
* finds a *new claimant's* lease, since we no longer hold the session
|
|
112
147
|
* either way and continuing the turn loop would duplicate the new
|
|
113
|
-
* holder's work.
|
|
114
|
-
* releases, so this is always `true`; it exists so callers already
|
|
115
|
-
* branch on it before the inbox makes keep-the-lease outcomes real.
|
|
148
|
+
* holder's work.
|
|
116
149
|
*/
|
|
117
150
|
leaseReleased: boolean;
|
|
118
151
|
}
|
|
152
|
+
export interface SweepOrphansArgs {
|
|
153
|
+
/** Limit the sweep to one session (default: all mailbox blobs). */
|
|
154
|
+
sessionId?: string;
|
|
155
|
+
/** Age gate (default {@link DEFAULT_ORPHAN_TTL_MS}). */
|
|
156
|
+
olderThanMs?: number;
|
|
157
|
+
}
|
|
158
|
+
export interface SweepOrphansResult {
|
|
159
|
+
/** Deleted blob ids as `<sessionId>/<eventId>`. */
|
|
160
|
+
deleted: string[];
|
|
161
|
+
}
|
|
119
162
|
/**
|
|
120
163
|
* The turn was fenced: a stale generation, a moved head, or a missing
|
|
121
164
|
* ledger. The caller must abort the turn and discard warm state.
|
|
@@ -134,7 +177,7 @@ export interface SessionLedgerOptions {
|
|
|
134
177
|
podId: string;
|
|
135
178
|
/** Lease TTL (default {@link LEASE_TTL_MS}). */
|
|
136
179
|
leaseTtlMs?: number;
|
|
137
|
-
/** Time source for lease expiry (default `Date.now`). */
|
|
180
|
+
/** Time source for lease expiry and blob ages (default `Date.now`). */
|
|
138
181
|
clock?: () => number;
|
|
139
182
|
/** Max attempts per CAS loop (default 16). */
|
|
140
183
|
maxCasAttempts?: number;
|
|
@@ -146,7 +189,7 @@ export interface SessionLedgerOptions {
|
|
|
146
189
|
/** Session id mint (default `ses_<24 hex>` like the session engine). */
|
|
147
190
|
newSessionId?: () => string;
|
|
148
191
|
}
|
|
149
|
-
/** Drives the
|
|
192
|
+
/** Drives the three ledger key families over a CAS-capable KV. */
|
|
150
193
|
export declare class SessionLedger {
|
|
151
194
|
private readonly kv;
|
|
152
195
|
private readonly podId;
|
|
@@ -158,18 +201,36 @@ export declare class SessionLedger {
|
|
|
158
201
|
constructor(options: SessionLedgerOptions);
|
|
159
202
|
private sessionKey;
|
|
160
203
|
private ledgerKey;
|
|
204
|
+
private mailboxKey;
|
|
205
|
+
private mailboxPrefix;
|
|
206
|
+
private emptyLedger;
|
|
161
207
|
/**
|
|
162
208
|
* Create-or-read the session identity for a continuation key. The create
|
|
163
|
-
* race has one winner (put-if-absent); losers read the winner's identity
|
|
209
|
+
* race has one winner (put-if-absent); losers read the winner's identity
|
|
210
|
+
* and append there.
|
|
164
211
|
*/
|
|
165
212
|
ensureSession(continuationKey: string, init?: {
|
|
166
213
|
sdkSessionRef?: string | null;
|
|
167
214
|
}): Promise<EnsureSessionResult>;
|
|
215
|
+
/**
|
|
216
|
+
* Make one event durable: payload blob first, then one CAS indexing its
|
|
217
|
+
* id into `pending`. The blob must land before the index — a pending id
|
|
218
|
+
* with no payload would break drain, while the reverse (blob without
|
|
219
|
+
* index, i.e. a crash between the two writes) is a sweepable orphan.
|
|
220
|
+
* Idempotent by `eventId`: `pending` is a set, so redelivery re-runs are
|
|
221
|
+
* no-ops. The CAS in step two is the ack point — callers ack the source
|
|
222
|
+
* only after this resolves.
|
|
223
|
+
*/
|
|
224
|
+
appendEvent(sessionId: string, event: LedgerEventInput): Promise<{
|
|
225
|
+
appended: boolean;
|
|
226
|
+
}>;
|
|
168
227
|
/**
|
|
169
228
|
* Try to take the session lease, creating the ledger record on first
|
|
170
229
|
* contact. Succeeds only when the lease is null or expired; the CAS
|
|
171
230
|
* bumps the acquisition generation, fencing every prior holder. A
|
|
172
|
-
* losing caller
|
|
231
|
+
* losing caller walks away — the holder's commit sees any appended
|
|
232
|
+
* events in the same CAS value, and the janitor recovers sessions
|
|
233
|
+
* whose holder died.
|
|
173
234
|
*/
|
|
174
235
|
claim(sessionId: string): Promise<ClaimResult>;
|
|
175
236
|
/**
|
|
@@ -178,9 +239,19 @@ export declare class SessionLedger {
|
|
|
178
239
|
* new legitimate holder.
|
|
179
240
|
*/
|
|
180
241
|
heartbeat(sessionId: string, generation: number): Promise<HeartbeatResult>;
|
|
242
|
+
/**
|
|
243
|
+
* Read the pending mailbox: fetch each indexed payload blob and return
|
|
244
|
+
* them sorted by `sourceTs`, then `eventId` (mailbox order ≠ source
|
|
245
|
+
* order is a stated non-guarantee; this is the drain order). The
|
|
246
|
+
* returned `head` is the `expectedHead` for the matching commit.
|
|
247
|
+
*/
|
|
248
|
+
drain(sessionId: string): Promise<DrainResult>;
|
|
181
249
|
/**
|
|
182
250
|
* Commit one turn. The single CAS is the commit point: it bumps `head`,
|
|
183
|
-
*
|
|
251
|
+
* removes ONLY the drained ids from `pending`, releases the lease iff
|
|
252
|
+
* nothing is left pending, and records `commitId` — atomically. A
|
|
253
|
+
* non-empty result `pending` means events landed mid-turn: the lease was
|
|
254
|
+
* kept and the caller drains again.
|
|
184
255
|
*
|
|
185
256
|
* Ambiguous outcomes (the KV threw and we never saw the CAS result) are
|
|
186
257
|
* resolved by re-reading, never by blind-retrying: `head` advanced to
|
|
@@ -190,15 +261,33 @@ export declare class SessionLedger {
|
|
|
190
261
|
*/
|
|
191
262
|
commit(sessionId: string, args: CommitArgs): Promise<CommitResult>;
|
|
192
263
|
/**
|
|
193
|
-
* Release a held lease without committing — graceful shutdown,
|
|
194
|
-
*
|
|
195
|
-
* holder's release is a no-op
|
|
196
|
-
* the
|
|
264
|
+
* Release a held lease without committing — graceful shutdown, a turn
|
|
265
|
+
* that failed before its commit, or a claim that found nothing to
|
|
266
|
+
* drain. Fenced by generation: a stale holder's release is a no-op
|
|
267
|
+
* (the session has moved on). `head` and the acquisition counter are
|
|
268
|
+
* untouched, so prior holders stay fenced.
|
|
197
269
|
*/
|
|
198
270
|
release(sessionId: string, generation: number): Promise<{
|
|
199
271
|
released: boolean;
|
|
200
272
|
}>;
|
|
201
273
|
/** Parsed ledger value for one session, or `undefined` when never created. */
|
|
202
274
|
readLedger(sessionId: string): Promise<LedgerSnapshot | undefined>;
|
|
275
|
+
/**
|
|
276
|
+
* All ledgers under this prefix (the janitor's scan). An unparseable
|
|
277
|
+
* record is skipped — reported through `onSkip` — never thrown: one
|
|
278
|
+
* corrupt value must degrade that one session, not abort the scan and
|
|
279
|
+
* kill the whole agent's recovery pass.
|
|
280
|
+
*/
|
|
281
|
+
listLedgers(onSkip?: (key: string, error: unknown) => void): Promise<LedgerSnapshot[]>;
|
|
282
|
+
/**
|
|
283
|
+
* Delete mailbox blobs that are (a) not referenced by their session's
|
|
284
|
+
* `pending` and (b) older than the TTL. Covers both true orphans (a
|
|
285
|
+
* crash between the payload put and the ledger CAS) and consumed blobs
|
|
286
|
+
* whose ids a commit already removed. Membership is checked against a
|
|
287
|
+
* ledger read taken *after* listing the blobs, so a blob whose append
|
|
288
|
+
* CAS is in flight is never swept: its id is either already in
|
|
289
|
+
* `pending`, or the blob is younger than any sane TTL.
|
|
290
|
+
*/
|
|
291
|
+
sweepOrphans(args?: SweepOrphansArgs): Promise<SweepOrphansResult>;
|
|
203
292
|
}
|
|
204
293
|
//# sourceMappingURL=session-ledger.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"session-ledger.d.ts","sourceRoot":"","sources":["../../src/ledger/session-ledger.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"session-ledger.d.ts","sourceRoot":"","sources":["../../src/ledger/session-ledger.ts"],"names":[],"mappings":"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"}
|