@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.
@@ -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
- /** Drop the target after this many successful warms; unlimited when absent. */
16
+ /** Legacy/unpriced-auto warm cap; unlimited when absent. */
16
17
  maxWarms?: number;
17
- /** Idle bound replacing the main or subagent default for this target. */
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
- * Bounds, in the order they act: a target retires once its last confirmed
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
- * Bounds, in the order they act: a target retires once its last confirmed
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.pruneStale();
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 (window && !isWithinCacheKeepWindow(window, new Date(this.now()))) {
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.drop(sessionKey);
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
- this.targets.set(sessionKey, {
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 target of this.targets.values())
192
- this.clearRetry(target);
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
- if (window && !isWithinCacheKeepWindow(window, new Date(this.now()))) {
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 (target.maxWarms !== undefined && target.warmCount >= target.maxWarms) {
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
- // Sustain exempts main sessions from the idle cap only; the lifetime,
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
- const maxIdleMs = target.maxIdleMs ?? this.idleDefault(target.isSubagent);
481
- if (target.lastRealRequestAt >= now - maxIdleMs)
664
+ if (!this.usesLegacyBounds(target))
482
665
  continue;
483
- this.log?.debug('cachekeep pruned idle target', {
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
- constructor();
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
- constructor() {
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 and enrollment token that authorized it. A receipt
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
  /**