@cortexkit/common-auth 0.41.1 → 0.43.0
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/dist/cachekeep/index.d.ts +1 -1
- package/dist/cachekeep/manager.d.ts +50 -4
- package/dist/cachekeep/manager.js +241 -33
- package/dist/claustrum/availability.d.ts +7 -1
- package/dist/claustrum/availability.js +9 -1
- package/dist/claustrum/custody.d.ts +11 -2
- package/dist/claustrum/custody.js +89 -31
- package/dist/claustrum/enrollment.d.ts +4 -0
- package/dist/claustrum/enrollment.js +33 -2
- package/dist/claustrum/host.js +11 -7
- package/dist/claustrum/index.d.ts +1 -1
- package/dist/claustrum/index.js +1 -1
- package/dist/fs/lock-record.d.ts +19 -0
- package/dist/fs/lock-record.js +55 -0
- package/dist/fs/refresh-file-lock.js +148 -92
- package/dist/fs/with-lock.js +19 -13
- package/dist/quota-sidebar/index.d.ts +2 -36
- package/dist/quota-sidebar/index.jsx +28 -344
- package/dist/routing-accessor/cache-policy.d.ts +3 -0
- package/dist/routing-accessor/cache-policy.js +11 -0
- package/dist/routing-accessor/index.d.ts +48 -5
- package/dist/routing-accessor/index.js +136 -5
- package/dist/setup/enroll.js +2 -1
- package/dist/setup/types.d.ts +1 -0
- package/dist/tui-build/build-tui.js +26 -23
- package/package.json +7 -2
- package/src/quota-sidebar/index.tsx +49 -607
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
export type { CacheKeepDecision, CacheKeepDecisionInput } from './decision.js';
|
|
2
2
|
export { decideCacheKeep } from './decision.js';
|
|
3
|
-
export type { CacheKeepAdapter, CacheKeepBackoff, CacheKeepLogger, CacheKeepManagerOptions, CacheKeepProfile, CacheKeepSendInput, CacheKeepStatus, CacheKeepTargetStatus, CacheKeepTargetView, CacheKeepTrackInput, CacheKeepTrackResult, } from './manager.js';
|
|
3
|
+
export type { CacheKeepAdapter, CacheKeepBackoff, CacheKeepLogger, CacheKeepManagerOptions, CacheKeepPlan, CacheKeepProfile, CacheKeepSendInput, CacheKeepStatus, CacheKeepTargetStatus, CacheKeepTargetView, CacheKeepTrackInput, CacheKeepTrackResult, } from './manager.js';
|
|
4
4
|
export { CacheKeepManager } from './manager.js';
|
|
5
5
|
export type { CacheKeepWindow } from './window.js';
|
|
6
6
|
export { isWithinCacheKeepWindow, normalizeCacheKeepWindow, } from './window.js';
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { SessionCacheHours, SessionKeepWarmMode } from '../routing-accessor/cache-policy.js';
|
|
1
2
|
import { type CacheKeepWindow } from './window.js';
|
|
2
3
|
export interface CacheKeepLogger {
|
|
3
4
|
debug(message: string, data?: unknown): void;
|
|
@@ -12,9 +13,9 @@ export interface CacheKeepLogger {
|
|
|
12
13
|
export interface CacheKeepProfile {
|
|
13
14
|
/** Provider cache lifetime for this request; defaults to the manager's `ttlMs`. */
|
|
14
15
|
ttlMs?: number;
|
|
15
|
-
/**
|
|
16
|
+
/** Legacy/unpriced-auto warm cap; unlimited when absent. */
|
|
16
17
|
maxWarms?: number;
|
|
17
|
-
/**
|
|
18
|
+
/** Legacy/unpriced-auto idle bound replacing the main or subagent default. */
|
|
18
19
|
maxIdleMs?: number;
|
|
19
20
|
}
|
|
20
21
|
/** What the plugin sees of a tracked target. */
|
|
@@ -34,12 +35,32 @@ export interface CacheKeepSendInput<M> {
|
|
|
34
35
|
/** Aborted on the warm timeout and when the manager stops. */
|
|
35
36
|
signal: AbortSignal;
|
|
36
37
|
}
|
|
38
|
+
/** A fresh, plugin-validated session policy with optional provider prices. */
|
|
39
|
+
export interface CacheKeepPlan {
|
|
40
|
+
mode: SessionKeepWarmMode;
|
|
41
|
+
hours?: SessionCacheHours;
|
|
42
|
+
costs?: {
|
|
43
|
+
nextWarm: number;
|
|
44
|
+
rewrite: number;
|
|
45
|
+
};
|
|
46
|
+
}
|
|
37
47
|
/**
|
|
38
48
|
* The provider half of keep-warm. The manager decides when and what to warm;
|
|
39
49
|
* the plugin turns a captured request into a replay, resolves the account's
|
|
40
50
|
* credential, sends it and reads usage back.
|
|
41
51
|
*/
|
|
42
52
|
export interface CacheKeepAdapter<M> {
|
|
53
|
+
/** Read a fresh policy; undefined preserves legacy only if never planned. */
|
|
54
|
+
plan?(sessionKey: string): CacheKeepPlan | undefined;
|
|
55
|
+
/** Successful warm reports never block scheduling. */
|
|
56
|
+
onWarmed?(sessionKey: string, input: {
|
|
57
|
+
at: number;
|
|
58
|
+
}): void | Promise<void>;
|
|
59
|
+
/** Report retirement only after a target has successfully warmed. */
|
|
60
|
+
onWarmStopped?(sessionKey: string, input: {
|
|
61
|
+
at: number;
|
|
62
|
+
reason: string;
|
|
63
|
+
}): void | Promise<void>;
|
|
43
64
|
/** Build the replay body from the captured one. A throw backs the target off. */
|
|
44
65
|
buildBody(target: CacheKeepTargetView<M>): string | Promise<string>;
|
|
45
66
|
/**
|
|
@@ -107,7 +128,7 @@ export type CacheKeepTrackResult = {
|
|
|
107
128
|
tracked: true;
|
|
108
129
|
} | {
|
|
109
130
|
tracked: false;
|
|
110
|
-
reason: 'body-exceeds-max-bytes' | 'outside-window';
|
|
131
|
+
reason: 'body-exceeds-max-bytes' | 'outside-window' | 'unsupported' | 'session-ended';
|
|
111
132
|
};
|
|
112
133
|
export type CacheKeepTrackInput<M> = {
|
|
113
134
|
sessionKey: string;
|
|
@@ -122,6 +143,7 @@ export type CacheKeepTrackInput<M> = {
|
|
|
122
143
|
});
|
|
123
144
|
export interface CacheKeepTargetStatus {
|
|
124
145
|
sessionKey: string;
|
|
146
|
+
mode?: SessionKeepWarmMode;
|
|
125
147
|
accountId: string | undefined;
|
|
126
148
|
isSubagent: boolean;
|
|
127
149
|
cacheExpiresAt: number;
|
|
@@ -151,7 +173,7 @@ export interface CacheKeepStatus {
|
|
|
151
173
|
* Keeps idle prompt caches warm: one target per session holding the latest
|
|
152
174
|
* request body, replayed just before the provider's cache would expire.
|
|
153
175
|
*
|
|
154
|
-
*
|
|
176
|
+
* Without a session plan, bounds act in this order: a target retires once its last confirmed
|
|
155
177
|
* cache lifetime ends (`cacheExpiresAt`, set by its capture or its last
|
|
156
178
|
* successful warm), whatever else holds, because replaying a history whose
|
|
157
179
|
* cache has expired rebuilds a cold cache instead of keeping a warm one
|
|
@@ -165,9 +187,13 @@ export interface CacheKeepStatus {
|
|
|
165
187
|
* (expiry minus the warm timeout and 5 seconds). Only default-policy retries
|
|
166
188
|
* observe that deadline: first attempts and explicit backoff policies retain
|
|
167
189
|
* their existing lead-time scheduling, bounded by the cache lifetime.
|
|
190
|
+
* Session plans use the shared decision rule and one-shot due timers instead;
|
|
191
|
+
* only unpriced auto keeps the legacy idle and profile warm bounds. Lifetime,
|
|
192
|
+
* target-count, byte and LRU bounds apply to every target.
|
|
168
193
|
*/
|
|
169
194
|
export declare class CacheKeepManager<M = undefined> {
|
|
170
195
|
private readonly targets;
|
|
196
|
+
private readonly lastDropReasons;
|
|
171
197
|
private readonly adapter;
|
|
172
198
|
private readonly now;
|
|
173
199
|
private readonly log;
|
|
@@ -189,6 +215,7 @@ export declare class CacheKeepManager<M = undefined> {
|
|
|
189
215
|
private totalBytes;
|
|
190
216
|
private tickPromise;
|
|
191
217
|
private disposed;
|
|
218
|
+
private planWarningLogged;
|
|
192
219
|
private abortController;
|
|
193
220
|
constructor(options: CacheKeepManagerOptions<M>);
|
|
194
221
|
/**
|
|
@@ -202,6 +229,17 @@ export declare class CacheKeepManager<M = undefined> {
|
|
|
202
229
|
start(): void;
|
|
203
230
|
/** Disarm, abort any warm in flight and forget every target. */
|
|
204
231
|
stop(): void;
|
|
232
|
+
/**
|
|
233
|
+
* Read whether a session is armed, without I/O or callbacks. Stop reasons
|
|
234
|
+
* include manager-internal values: plugins must filter them through
|
|
235
|
+
* isCacheWarmStopReason for billing, leaving unknown reasons out, not guessing.
|
|
236
|
+
*/
|
|
237
|
+
warming(sessionKey: string): {
|
|
238
|
+
on: true;
|
|
239
|
+
} | {
|
|
240
|
+
on: false;
|
|
241
|
+
stopReason?: string;
|
|
242
|
+
};
|
|
205
243
|
/** A snapshot without captured bodies, which can hold prompt content. */
|
|
206
244
|
status(): CacheKeepStatus;
|
|
207
245
|
/**
|
|
@@ -219,6 +257,13 @@ export declare class CacheKeepManager<M = undefined> {
|
|
|
219
257
|
private retireIfExpired;
|
|
220
258
|
private isCurrent;
|
|
221
259
|
private view;
|
|
260
|
+
private readPlan;
|
|
261
|
+
private refreshPlan;
|
|
262
|
+
private usesLegacyBounds;
|
|
263
|
+
private planDecision;
|
|
264
|
+
private clearPlanTimer;
|
|
265
|
+
private schedulePlan;
|
|
266
|
+
private report;
|
|
222
267
|
private fail;
|
|
223
268
|
private lastRetryStart;
|
|
224
269
|
private canRetry;
|
|
@@ -227,6 +272,7 @@ export declare class CacheKeepManager<M = undefined> {
|
|
|
227
272
|
private warm;
|
|
228
273
|
private idleDefault;
|
|
229
274
|
private pruneStale;
|
|
275
|
+
private retireIfIdle;
|
|
230
276
|
private leastRecentlyTouched;
|
|
231
277
|
private drop;
|
|
232
278
|
}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { combineAbortSignals } from '../util/any-signal.js';
|
|
2
|
+
import { decideCacheKeep } from './decision.js';
|
|
2
3
|
import { classifyFailure } from './failure.js';
|
|
3
4
|
import { isWithinCacheKeepWindow } from './window.js';
|
|
4
5
|
const DEFAULT_TTL_MS = 5 * 60_000;
|
|
@@ -21,7 +22,7 @@ function positive(value, fallback) {
|
|
|
21
22
|
* Keeps idle prompt caches warm: one target per session holding the latest
|
|
22
23
|
* request body, replayed just before the provider's cache would expire.
|
|
23
24
|
*
|
|
24
|
-
*
|
|
25
|
+
* Without a session plan, bounds act in this order: a target retires once its last confirmed
|
|
25
26
|
* cache lifetime ends (`cacheExpiresAt`, set by its capture or its last
|
|
26
27
|
* successful warm), whatever else holds, because replaying a history whose
|
|
27
28
|
* cache has expired rebuilds a cold cache instead of keeping a warm one
|
|
@@ -35,9 +36,13 @@ function positive(value, fallback) {
|
|
|
35
36
|
* (expiry minus the warm timeout and 5 seconds). Only default-policy retries
|
|
36
37
|
* observe that deadline: first attempts and explicit backoff policies retain
|
|
37
38
|
* their existing lead-time scheduling, bounded by the cache lifetime.
|
|
39
|
+
* Session plans use the shared decision rule and one-shot due timers instead;
|
|
40
|
+
* only unpriced auto keeps the legacy idle and profile warm bounds. Lifetime,
|
|
41
|
+
* target-count, byte and LRU bounds apply to every target.
|
|
38
42
|
*/
|
|
39
43
|
export class CacheKeepManager {
|
|
40
44
|
targets = new Map();
|
|
45
|
+
lastDropReasons = new Map();
|
|
41
46
|
adapter;
|
|
42
47
|
now;
|
|
43
48
|
log;
|
|
@@ -59,6 +64,7 @@ export class CacheKeepManager {
|
|
|
59
64
|
totalBytes = 0;
|
|
60
65
|
tickPromise = null;
|
|
61
66
|
disposed = false;
|
|
67
|
+
planWarningLogged = false;
|
|
62
68
|
abortController = new AbortController();
|
|
63
69
|
constructor(options) {
|
|
64
70
|
this.adapter = options.adapter;
|
|
@@ -88,7 +94,17 @@ export class CacheKeepManager {
|
|
|
88
94
|
*/
|
|
89
95
|
track(input) {
|
|
90
96
|
const { sessionKey, bodyText } = input;
|
|
91
|
-
this.
|
|
97
|
+
const previous = this.targets.get(sessionKey);
|
|
98
|
+
const plan = this.readPlan(sessionKey);
|
|
99
|
+
if (!plan && previous?.plan) {
|
|
100
|
+
this.drop(sessionKey, 'session-ended');
|
|
101
|
+
return { tracked: false, reason: 'session-ended' };
|
|
102
|
+
}
|
|
103
|
+
if (plan?.mode === 'off') {
|
|
104
|
+
this.drop(sessionKey, 'unsupported');
|
|
105
|
+
return { tracked: false, reason: 'unsupported' };
|
|
106
|
+
}
|
|
107
|
+
this.pruneStale(plan ? sessionKey : undefined);
|
|
92
108
|
const bodyBytes = Buffer.byteLength(bodyText, 'utf8');
|
|
93
109
|
if (bodyBytes > this.maxBytes) {
|
|
94
110
|
this.log?.debug('cachekeep track skipped (body exceeds maxBytes)', {
|
|
@@ -99,7 +115,9 @@ export class CacheKeepManager {
|
|
|
99
115
|
return { tracked: false, reason: 'body-exceeds-max-bytes' };
|
|
100
116
|
}
|
|
101
117
|
const window = this.getWindow?.();
|
|
102
|
-
if (
|
|
118
|
+
if (!plan &&
|
|
119
|
+
window &&
|
|
120
|
+
!isWithinCacheKeepWindow(window, new Date(this.now()))) {
|
|
103
121
|
this.log?.debug('cachekeep track skipped (outside window)', {
|
|
104
122
|
sessionKey,
|
|
105
123
|
startHour: window.startHour,
|
|
@@ -109,7 +127,8 @@ export class CacheKeepManager {
|
|
|
109
127
|
}
|
|
110
128
|
// Delete before re-adding so a retracked session is also the most recent
|
|
111
129
|
// in insertion order.
|
|
112
|
-
this.
|
|
130
|
+
const hasWarmed = this.targets.get(sessionKey)?.hasWarmed ?? false;
|
|
131
|
+
this.drop(sessionKey, null);
|
|
113
132
|
while (this.targets.size >= this.maxTargets ||
|
|
114
133
|
(this.totalBytes + bodyBytes > this.maxBytes && this.targets.size > 0)) {
|
|
115
134
|
const evictKey = this.leastRecentlyTouched();
|
|
@@ -118,7 +137,7 @@ export class CacheKeepManager {
|
|
|
118
137
|
this.log?.debug('cachekeep evicted least recently used target', {
|
|
119
138
|
sessionKey: evictKey,
|
|
120
139
|
});
|
|
121
|
-
this.drop(evictKey);
|
|
140
|
+
this.drop(evictKey, 'evicted');
|
|
122
141
|
}
|
|
123
142
|
const isSubagent = input.isSubagent === true;
|
|
124
143
|
const accountId = input.accountId || undefined;
|
|
@@ -130,7 +149,10 @@ export class CacheKeepManager {
|
|
|
130
149
|
});
|
|
131
150
|
const ttlMs = positive(profile?.ttlMs, this.ttlMs);
|
|
132
151
|
const now = this.now();
|
|
133
|
-
|
|
152
|
+
const target = {
|
|
153
|
+
plan,
|
|
154
|
+
warmCostSoFar: 0,
|
|
155
|
+
hasWarmed,
|
|
134
156
|
bodyText,
|
|
135
157
|
bodyBytes,
|
|
136
158
|
accountId,
|
|
@@ -147,10 +169,14 @@ export class CacheKeepManager {
|
|
|
147
169
|
lastRealRequestAt: now,
|
|
148
170
|
failures: 0,
|
|
149
171
|
warmCount: 0,
|
|
150
|
-
}
|
|
172
|
+
};
|
|
173
|
+
this.targets.set(sessionKey, target);
|
|
174
|
+
this.lastDropReasons.delete(sessionKey);
|
|
151
175
|
this.totalBytes += bodyBytes;
|
|
152
176
|
this.log?.debug('cachekeep captured target', { sessionKey, accountId });
|
|
153
177
|
this.start();
|
|
178
|
+
if (plan)
|
|
179
|
+
this.planDecision(sessionKey, target);
|
|
154
180
|
return { tracked: true };
|
|
155
181
|
}
|
|
156
182
|
/** Forget a session, e.g. when the host deletes it. */
|
|
@@ -188,12 +214,27 @@ export class CacheKeepManager {
|
|
|
188
214
|
this.timer = null;
|
|
189
215
|
}
|
|
190
216
|
this.startedAt = null;
|
|
191
|
-
for (const
|
|
192
|
-
this.
|
|
193
|
-
this.targets.clear();
|
|
217
|
+
for (const sessionKey of this.targets.keys())
|
|
218
|
+
this.drop(sessionKey, 'stopped');
|
|
194
219
|
this.totalBytes = 0;
|
|
195
220
|
this.log?.debug('cachekeep stopped');
|
|
196
221
|
}
|
|
222
|
+
/**
|
|
223
|
+
* Read whether a session is armed, without I/O or callbacks. Stop reasons
|
|
224
|
+
* include manager-internal values: plugins must filter them through
|
|
225
|
+
* isCacheWarmStopReason for billing, leaving unknown reasons out, not guessing.
|
|
226
|
+
*/
|
|
227
|
+
warming(sessionKey) {
|
|
228
|
+
try {
|
|
229
|
+
if (this.targets.has(sessionKey))
|
|
230
|
+
return { on: true };
|
|
231
|
+
const stopReason = this.lastDropReasons.get(sessionKey);
|
|
232
|
+
return { on: false, ...(stopReason !== undefined ? { stopReason } : {}) };
|
|
233
|
+
}
|
|
234
|
+
catch {
|
|
235
|
+
return { on: false };
|
|
236
|
+
}
|
|
237
|
+
}
|
|
197
238
|
/** A snapshot without captured bodies, which can hold prompt content. */
|
|
198
239
|
status() {
|
|
199
240
|
const window = this.getWindow?.();
|
|
@@ -211,6 +252,7 @@ export class CacheKeepManager {
|
|
|
211
252
|
...(window ? { window } : {}),
|
|
212
253
|
targets: [...this.targets].map(([sessionKey, target]) => ({
|
|
213
254
|
sessionKey,
|
|
255
|
+
...(target.plan ? { mode: target.plan.mode } : {}),
|
|
214
256
|
accountId: target.accountId,
|
|
215
257
|
isSubagent: target.isSubagent,
|
|
216
258
|
cacheExpiresAt: target.cacheExpiresAt,
|
|
@@ -249,20 +291,33 @@ export class CacheKeepManager {
|
|
|
249
291
|
// their cache lifetime ends, so one still alive when the window reopens
|
|
250
292
|
// is warmed again.
|
|
251
293
|
const window = this.getWindow?.();
|
|
252
|
-
|
|
253
|
-
return;
|
|
254
|
-
}
|
|
294
|
+
const outsideWindow = window && !isWithinCacheKeepWindow(window, new Date(this.now()));
|
|
255
295
|
for (const [sessionKey, target] of [...this.targets]) {
|
|
256
296
|
if (this.disposed)
|
|
257
297
|
return;
|
|
258
298
|
if (this.targets.get(sessionKey) !== target)
|
|
259
299
|
continue;
|
|
300
|
+
if (!this.refreshPlan(sessionKey, target))
|
|
301
|
+
continue;
|
|
260
302
|
const now = this.now();
|
|
303
|
+
if (target.plan) {
|
|
304
|
+
const decision = this.planDecision(sessionKey, target);
|
|
305
|
+
if (decision.action !== 'warm')
|
|
306
|
+
continue;
|
|
307
|
+
if (target.backoffUntil !== undefined && now < target.backoffUntil) {
|
|
308
|
+
this.schedulePlan(sessionKey, target, target.backoffUntil);
|
|
309
|
+
continue;
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
else {
|
|
313
|
+
if (outsideWindow)
|
|
314
|
+
continue;
|
|
315
|
+
if (target.cacheExpiresAt > now + this.leadMs)
|
|
316
|
+
continue;
|
|
317
|
+
}
|
|
261
318
|
if (target.backoffUntil !== undefined && now < target.backoffUntil) {
|
|
262
319
|
continue;
|
|
263
320
|
}
|
|
264
|
-
if (target.cacheExpiresAt > now + this.leadMs)
|
|
265
|
-
continue;
|
|
266
321
|
if (!this.canRetry(target))
|
|
267
322
|
continue;
|
|
268
323
|
await this.warm(sessionKey, target);
|
|
@@ -282,7 +337,7 @@ export class CacheKeepManager {
|
|
|
282
337
|
cacheExpiresAt: target.cacheExpiresAt,
|
|
283
338
|
failures: target.failures,
|
|
284
339
|
});
|
|
285
|
-
this.drop(sessionKey);
|
|
340
|
+
this.drop(sessionKey, target.plan ? 'cost-cap' : 'expired');
|
|
286
341
|
return true;
|
|
287
342
|
}
|
|
288
343
|
isCurrent(sessionKey, target) {
|
|
@@ -299,6 +354,114 @@ export class CacheKeepManager {
|
|
|
299
354
|
ttlMs: target.ttlMs,
|
|
300
355
|
};
|
|
301
356
|
}
|
|
357
|
+
readPlan(sessionKey) {
|
|
358
|
+
try {
|
|
359
|
+
return this.adapter.plan?.(sessionKey);
|
|
360
|
+
}
|
|
361
|
+
catch {
|
|
362
|
+
if (!this.planWarningLogged) {
|
|
363
|
+
this.planWarningLogged = true;
|
|
364
|
+
this.log?.warn('cachekeep plan unavailable');
|
|
365
|
+
}
|
|
366
|
+
return undefined;
|
|
367
|
+
}
|
|
368
|
+
}
|
|
369
|
+
refreshPlan(sessionKey, target) {
|
|
370
|
+
const plan = this.readPlan(sessionKey);
|
|
371
|
+
if (!plan && target.plan) {
|
|
372
|
+
this.drop(sessionKey, 'session-ended');
|
|
373
|
+
return false;
|
|
374
|
+
}
|
|
375
|
+
target.plan = plan;
|
|
376
|
+
if (plan?.mode === 'off') {
|
|
377
|
+
this.drop(sessionKey, 'unsupported');
|
|
378
|
+
return false;
|
|
379
|
+
}
|
|
380
|
+
return true;
|
|
381
|
+
}
|
|
382
|
+
usesLegacyBounds(target) {
|
|
383
|
+
return !target.plan || (target.plan.mode === 'auto' && !target.plan.costs);
|
|
384
|
+
}
|
|
385
|
+
planDecision(sessionKey, target) {
|
|
386
|
+
const plan = target.plan;
|
|
387
|
+
if (!plan)
|
|
388
|
+
return { action: 'stop', reason: 'session-ended' };
|
|
389
|
+
if (this.usesLegacyBounds(target)) {
|
|
390
|
+
if (this.retireIfIdle(sessionKey, target, this.getSustain?.() === true)) {
|
|
391
|
+
return { action: 'stop', reason: 'idle' };
|
|
392
|
+
}
|
|
393
|
+
if (target.maxWarms !== undefined &&
|
|
394
|
+
target.warmCount >= target.maxWarms) {
|
|
395
|
+
this.drop(sessionKey, 'count-cap');
|
|
396
|
+
return { action: 'stop', reason: 'count-cap' };
|
|
397
|
+
}
|
|
398
|
+
}
|
|
399
|
+
const decision = plan.mode === 'hours' && !plan.hours
|
|
400
|
+
? { action: 'stop', reason: 'unsupported' }
|
|
401
|
+
: decideCacheKeep({
|
|
402
|
+
...(plan.mode === 'hours'
|
|
403
|
+
? { mode: plan.mode, hours: plan.hours }
|
|
404
|
+
: { mode: plan.mode }),
|
|
405
|
+
now: this.now(),
|
|
406
|
+
ttlMs: target.ttlMs,
|
|
407
|
+
lastRealRequestAt: target.lastRealRequestAt,
|
|
408
|
+
lastWarmAt: target.lastWarmedAt,
|
|
409
|
+
warmsSinceLastRealRequest: target.warmCount,
|
|
410
|
+
...(plan.costs
|
|
411
|
+
? {
|
|
412
|
+
warmCostSoFar: target.warmCostSoFar,
|
|
413
|
+
nextWarmCost: plan.costs.nextWarm,
|
|
414
|
+
rewriteCost: plan.costs.rewrite,
|
|
415
|
+
}
|
|
416
|
+
: {}),
|
|
417
|
+
});
|
|
418
|
+
if (decision.action === 'stop')
|
|
419
|
+
this.drop(sessionKey, decision.reason);
|
|
420
|
+
else if (decision.action === 'wait') {
|
|
421
|
+
this.schedulePlan(sessionKey, target, Math.max(decision.until, target.backoffUntil ?? 0));
|
|
422
|
+
}
|
|
423
|
+
else
|
|
424
|
+
this.clearPlanTimer(target);
|
|
425
|
+
return decision;
|
|
426
|
+
}
|
|
427
|
+
clearPlanTimer(target) {
|
|
428
|
+
if (target.planTimer === undefined)
|
|
429
|
+
return;
|
|
430
|
+
this.clearIntervalImpl(target.planTimer);
|
|
431
|
+
target.planTimer = undefined;
|
|
432
|
+
target.planDueAt = undefined;
|
|
433
|
+
}
|
|
434
|
+
schedulePlan(sessionKey, target, until) {
|
|
435
|
+
if (target.planTimer !== undefined && target.planDueAt === until)
|
|
436
|
+
return;
|
|
437
|
+
this.clearPlanTimer(target);
|
|
438
|
+
target.planDueAt = until;
|
|
439
|
+
// Clear the injected interval before dispatch to make it a one-shot, just
|
|
440
|
+
// like retries. Waiting for an in-flight tick prevents a lost wake-up.
|
|
441
|
+
target.planTimer = this.setIntervalImpl(() => {
|
|
442
|
+
this.clearPlanTimer(target);
|
|
443
|
+
return (async () => {
|
|
444
|
+
await this.tickPromise;
|
|
445
|
+
if (this.isCurrent(sessionKey, target))
|
|
446
|
+
await this.tick();
|
|
447
|
+
})().catch((error) => {
|
|
448
|
+
this.log?.warn('cachekeep tick failed', classifyFailure(error, 'send'));
|
|
449
|
+
});
|
|
450
|
+
}, Math.max(0, until - this.now()));
|
|
451
|
+
if (typeof target.planTimer === 'object' && 'unref' in target.planTimer) {
|
|
452
|
+
target.planTimer.unref();
|
|
453
|
+
}
|
|
454
|
+
}
|
|
455
|
+
report(callback) {
|
|
456
|
+
try {
|
|
457
|
+
void Promise.resolve(callback()).catch(() => {
|
|
458
|
+
this.log?.debug('cachekeep report failed');
|
|
459
|
+
});
|
|
460
|
+
}
|
|
461
|
+
catch {
|
|
462
|
+
this.log?.debug('cachekeep report failed');
|
|
463
|
+
}
|
|
464
|
+
}
|
|
302
465
|
fail(sessionKey, target, message, failure, transient = false, status) {
|
|
303
466
|
if (!this.isCurrent(sessionKey, target))
|
|
304
467
|
return;
|
|
@@ -317,6 +480,9 @@ export class CacheKeepManager {
|
|
|
317
480
|
this.clearRetry(target);
|
|
318
481
|
if (fastRetry)
|
|
319
482
|
this.scheduleRetry(sessionKey, target, delay);
|
|
483
|
+
else if (target.plan) {
|
|
484
|
+
this.schedulePlan(sessionKey, target, target.backoffUntil);
|
|
485
|
+
}
|
|
320
486
|
this.log?.warn(message, {
|
|
321
487
|
sessionKey,
|
|
322
488
|
accountId: target.accountId,
|
|
@@ -383,7 +549,7 @@ export class CacheKeepManager {
|
|
|
383
549
|
accountId: target.accountId,
|
|
384
550
|
activeAccountId: active,
|
|
385
551
|
});
|
|
386
|
-
this.drop(sessionKey);
|
|
552
|
+
this.drop(sessionKey, 'account-changed');
|
|
387
553
|
return;
|
|
388
554
|
}
|
|
389
555
|
}
|
|
@@ -401,6 +567,13 @@ export class CacheKeepManager {
|
|
|
401
567
|
return;
|
|
402
568
|
if (!this.canRetry(target))
|
|
403
569
|
return;
|
|
570
|
+
if (!this.refreshPlan(sessionKey, target))
|
|
571
|
+
return;
|
|
572
|
+
if (target.plan &&
|
|
573
|
+
this.planDecision(sessionKey, target).action !== 'warm') {
|
|
574
|
+
return;
|
|
575
|
+
}
|
|
576
|
+
const nextWarmCost = target.plan?.costs?.nextWarm ?? 0;
|
|
404
577
|
const combined = combineAbortSignals([
|
|
405
578
|
AbortSignal.timeout(this.warmTimeoutMs),
|
|
406
579
|
this.abortController.signal,
|
|
@@ -450,45 +623,66 @@ export class CacheKeepManager {
|
|
|
450
623
|
this.clearRetry(target);
|
|
451
624
|
target.failures = 0;
|
|
452
625
|
target.warmCount += 1;
|
|
626
|
+
target.hasWarmed = true;
|
|
627
|
+
target.warmCostSoFar += nextWarmCost;
|
|
628
|
+
if (this.adapter.onWarmed) {
|
|
629
|
+
this.report(() => this.adapter.onWarmed?.(sessionKey, { at: now }));
|
|
630
|
+
}
|
|
453
631
|
this.log?.debug('cachekeep fired', {
|
|
454
632
|
sessionKey,
|
|
455
633
|
accountId: target.accountId,
|
|
456
634
|
warmCount: target.warmCount,
|
|
457
635
|
...usage,
|
|
458
636
|
});
|
|
459
|
-
if (
|
|
637
|
+
if (this.usesLegacyBounds(target) &&
|
|
638
|
+
target.maxWarms !== undefined &&
|
|
639
|
+
target.warmCount >= target.maxWarms) {
|
|
460
640
|
this.log?.debug('cachekeep retired target (warm cap reached)', {
|
|
461
641
|
sessionKey,
|
|
462
642
|
warmCount: target.warmCount,
|
|
463
643
|
});
|
|
464
|
-
this.drop(sessionKey);
|
|
644
|
+
this.drop(sessionKey, 'count-cap');
|
|
645
|
+
}
|
|
646
|
+
if (target.plan && this.isCurrent(sessionKey, target)) {
|
|
647
|
+
if (this.refreshPlan(sessionKey, target))
|
|
648
|
+
this.planDecision(sessionKey, target);
|
|
465
649
|
}
|
|
466
650
|
}
|
|
467
651
|
idleDefault(isSubagent) {
|
|
468
652
|
return isSubagent ? this.maxSubagentIdleMs : this.maxIdleWarmMs;
|
|
469
653
|
}
|
|
470
|
-
pruneStale() {
|
|
654
|
+
pruneStale(skipSessionKey) {
|
|
471
655
|
const now = this.now();
|
|
472
656
|
const sustain = this.getSustain?.() === true;
|
|
473
657
|
for (const [sessionKey, target] of [...this.targets]) {
|
|
658
|
+
if (sessionKey === skipSessionKey)
|
|
659
|
+
continue;
|
|
474
660
|
if (this.retireIfExpired(sessionKey, target))
|
|
475
661
|
continue;
|
|
476
|
-
|
|
477
|
-
// window, count, byte and warm caps still apply to them.
|
|
478
|
-
if (sustain && !target.isSubagent)
|
|
662
|
+
if (!this.refreshPlan(sessionKey, target))
|
|
479
663
|
continue;
|
|
480
|
-
|
|
481
|
-
if (target.lastRealRequestAt >= now - maxIdleMs)
|
|
664
|
+
if (!this.usesLegacyBounds(target))
|
|
482
665
|
continue;
|
|
483
|
-
this.
|
|
484
|
-
sessionKey,
|
|
485
|
-
accountId: target.accountId,
|
|
486
|
-
lastRealRequestAt: target.lastRealRequestAt,
|
|
487
|
-
maxIdleMs,
|
|
488
|
-
});
|
|
489
|
-
this.drop(sessionKey);
|
|
666
|
+
this.retireIfIdle(sessionKey, target, sustain, now);
|
|
490
667
|
}
|
|
491
668
|
}
|
|
669
|
+
retireIfIdle(sessionKey, target, sustain, now = this.now()) {
|
|
670
|
+
// Sustain exempts main sessions from the idle cap only; the lifetime,
|
|
671
|
+
// window, count, byte and warm caps still apply to them.
|
|
672
|
+
if (sustain && !target.isSubagent)
|
|
673
|
+
return false;
|
|
674
|
+
const maxIdleMs = target.maxIdleMs ?? this.idleDefault(target.isSubagent);
|
|
675
|
+
if (target.lastRealRequestAt >= now - maxIdleMs)
|
|
676
|
+
return false;
|
|
677
|
+
this.log?.debug('cachekeep pruned idle target', {
|
|
678
|
+
sessionKey,
|
|
679
|
+
accountId: target.accountId,
|
|
680
|
+
lastRealRequestAt: target.lastRealRequestAt,
|
|
681
|
+
maxIdleMs,
|
|
682
|
+
});
|
|
683
|
+
this.drop(sessionKey, 'idle');
|
|
684
|
+
return true;
|
|
685
|
+
}
|
|
492
686
|
leastRecentlyTouched() {
|
|
493
687
|
let evictKey;
|
|
494
688
|
let evictTouchedAt = Number.POSITIVE_INFINITY;
|
|
@@ -503,13 +697,27 @@ export class CacheKeepManager {
|
|
|
503
697
|
}
|
|
504
698
|
return evictKey;
|
|
505
699
|
}
|
|
506
|
-
drop(sessionKey) {
|
|
700
|
+
drop(sessionKey, reason = 'session-ended') {
|
|
507
701
|
const target = this.targets.get(sessionKey);
|
|
508
702
|
if (!target)
|
|
509
703
|
return false;
|
|
510
704
|
this.clearRetry(target);
|
|
705
|
+
this.clearPlanTimer(target);
|
|
511
706
|
this.totalBytes -= target.bodyBytes;
|
|
512
707
|
this.targets.delete(sessionKey);
|
|
708
|
+
if (reason !== null) {
|
|
709
|
+
this.lastDropReasons.delete(sessionKey);
|
|
710
|
+
this.lastDropReasons.set(sessionKey, reason);
|
|
711
|
+
while (this.lastDropReasons.size > this.maxTargets * 4) {
|
|
712
|
+
const oldest = this.lastDropReasons.keys().next();
|
|
713
|
+
if (oldest.done)
|
|
714
|
+
break;
|
|
715
|
+
this.lastDropReasons.delete(oldest.value);
|
|
716
|
+
}
|
|
717
|
+
}
|
|
718
|
+
if (reason !== null && target.hasWarmed && this.adapter.onWarmStopped) {
|
|
719
|
+
this.report(() => this.adapter.onWarmStopped?.(sessionKey, { at: this.now(), reason }));
|
|
720
|
+
}
|
|
513
721
|
return true;
|
|
514
722
|
}
|
|
515
723
|
}
|
|
@@ -85,6 +85,12 @@ export declare const VAULT_FAILURE_CLASSES: Readonly<{
|
|
|
85
85
|
* kind stays `unavailable` for callers handling ClaustrumConsumerError.
|
|
86
86
|
*/
|
|
87
87
|
export declare class ClaustrumUnreachableError extends ClaustrumConsumerError {
|
|
88
|
-
|
|
88
|
+
/**
|
|
89
|
+
* Non-secret host connection diagnostic. A missing accessor can recover
|
|
90
|
+
* once the host bridge installs; a failed accessor could not provide a client.
|
|
91
|
+
* Other unreachable failures leave this unset. Never use adapter error text.
|
|
92
|
+
*/
|
|
93
|
+
readonly reason?: 'host-accessor-missing' | 'host-accessor-failed';
|
|
94
|
+
constructor(reason?: ClaustrumUnreachableError['reason']);
|
|
89
95
|
}
|
|
90
96
|
export declare function classifyVaultFailure(error: unknown): VaultFailureClass;
|
|
@@ -87,9 +87,17 @@ export const VAULT_FAILURE_CLASSES = Object.freeze({
|
|
|
87
87
|
* kind stays `unavailable` for callers handling ClaustrumConsumerError.
|
|
88
88
|
*/
|
|
89
89
|
export class ClaustrumUnreachableError extends ClaustrumConsumerError {
|
|
90
|
-
|
|
90
|
+
/**
|
|
91
|
+
* Non-secret host connection diagnostic. A missing accessor can recover
|
|
92
|
+
* once the host bridge installs; a failed accessor could not provide a client.
|
|
93
|
+
* Other unreachable failures leave this unset. Never use adapter error text.
|
|
94
|
+
*/
|
|
95
|
+
reason;
|
|
96
|
+
constructor(reason) {
|
|
91
97
|
super('unavailable', 'Claustrum scoped operation unavailable');
|
|
92
98
|
this.name = 'ClaustrumUnreachableError';
|
|
99
|
+
if (reason === 'host-accessor-missing' || reason === 'host-accessor-failed')
|
|
100
|
+
this.reason = reason;
|
|
93
101
|
}
|
|
94
102
|
}
|
|
95
103
|
export function classifyVaultFailure(error) {
|
|
@@ -279,6 +279,15 @@ export declare class ClaustrumScopedCustody {
|
|
|
279
279
|
setTimeoutImpl?: typeof setTimeout;
|
|
280
280
|
clearTimeoutImpl?: typeof clearTimeout;
|
|
281
281
|
});
|
|
282
|
+
/**
|
|
283
|
+
* Replace the connection to the same vault without discarding receipts or
|
|
284
|
+
* their enrollment tokens. Open roster watches restart on the new client;
|
|
285
|
+
* their existing handles remain usable. Passing the current client does nothing.
|
|
286
|
+
* Neither client is closed here: the caller closes the old one, and custody's
|
|
287
|
+
* close()/dispose() still closes the client it holds at shutdown.
|
|
288
|
+
* While hosted, next must come from connectVaultHost, as in the constructor.
|
|
289
|
+
*/
|
|
290
|
+
replaceClient(next: ClaustrumScopedClient): void;
|
|
282
291
|
/** A watch losing its transport is the same outage as an unreachable read. */
|
|
283
292
|
transportLost(error?: unknown): void;
|
|
284
293
|
/** Any vault answer ends transport fallback, even when it refuses access. */
|
|
@@ -312,8 +321,8 @@ export declare class ClaustrumScopedCustody {
|
|
|
312
321
|
* Report that a send this consumer actually made was rejected. Only a 401
|
|
313
322
|
* is reported (the vault refuses 429, 402 and 5xx reports), addressed by
|
|
314
323
|
* credential id with the exact record version that send was served, and
|
|
315
|
-
* sent through the client
|
|
316
|
-
* this custody did not issue is refused rather than reported.
|
|
324
|
+
* sent through the current client with the enrollment token that authorized
|
|
325
|
+
* it. A receipt this custody did not issue is refused rather than reported.
|
|
317
326
|
*/
|
|
318
327
|
reportFailure(attempt: ClaustrumScopedAttempt, status: number, reporterSource: ClaustrumReporterSource): Promise<void>;
|
|
319
328
|
/**
|