@cortexkit/common-auth 0.35.0 → 0.37.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.
@@ -0,0 +1,11 @@
1
+ type FailureStage = 'authorization' | 'send' | 'response';
2
+ /** Keep diagnostics useful without retaining provider text, credentials or error causes. */
3
+ export declare function classifyFailure(error: unknown, stage: FailureStage, status?: number): {
4
+ stage: 'response';
5
+ class: number;
6
+ } | {
7
+ stage: FailureStage;
8
+ class: string;
9
+ };
10
+ export type Failure = ReturnType<typeof classifyFailure>;
11
+ export {};
@@ -0,0 +1,59 @@
1
+ const ERROR_NAMES = ['AbortError', 'TimeoutError', 'TypeError'];
2
+ const NETWORK_CODES = [
3
+ 'ECONNRESET',
4
+ 'ECONNREFUSED',
5
+ 'ETIMEDOUT',
6
+ 'EPIPE',
7
+ 'ENOTFOUND',
8
+ 'EAI_AGAIN',
9
+ 'UND_ERR_CONNECT_TIMEOUT',
10
+ 'UND_ERR_HEADERS_TIMEOUT',
11
+ 'UND_ERR_HEADERS_OVERFLOW',
12
+ 'UND_ERR_BODY_TIMEOUT',
13
+ 'UND_ERR_RESPONSE_STATUS_CODE',
14
+ 'UND_ERR_INVALID_ARG',
15
+ 'UND_ERR_INVALID_RETURN_VALUE',
16
+ 'UND_ERR_ABORTED',
17
+ 'UND_ERR_CLIENT_DESTROYED',
18
+ 'UND_ERR_CLIENT_CLOSED',
19
+ 'UND_ERR_SOCKET',
20
+ 'UND_ERR_NOT_SUPPORTED',
21
+ 'UND_ERR_REQ_CONTENT_LENGTH_MISMATCH',
22
+ 'UND_ERR_RES_CONTENT_LENGTH_MISMATCH',
23
+ 'UND_ERR_INFO',
24
+ 'UND_ERR_RES_EXCEEDED_MAX_SIZE',
25
+ 'UND_ERR_PRX_TLS',
26
+ ];
27
+ function allowed(values, value) {
28
+ return typeof value === 'string' && values.includes(value);
29
+ }
30
+ /** Keep diagnostics useful without retaining provider text, credentials or error causes. */
31
+ export function classifyFailure(error, stage, status) {
32
+ try {
33
+ if (status !== undefined &&
34
+ Number.isInteger(status) &&
35
+ status >= 100 &&
36
+ status <= 599 &&
37
+ (status < 200 || status >= 300)) {
38
+ return { stage: 'response', class: status };
39
+ }
40
+ if (typeof error === 'object' && error !== null) {
41
+ const fields = error;
42
+ const name = fields.name;
43
+ if (name === 'AbortError' || name === 'TimeoutError')
44
+ return { stage, class: name };
45
+ const code = fields.code;
46
+ if (allowed(NETWORK_CODES, code))
47
+ return { stage, class: code };
48
+ const causeCode = fields.cause?.code;
49
+ if (allowed(NETWORK_CODES, causeCode))
50
+ return { stage, class: causeCode };
51
+ if (allowed(ERROR_NAMES, name))
52
+ return { stage, class: name };
53
+ }
54
+ }
55
+ catch {
56
+ // Host errors can have throwing accessors; never inspect or stringify them further.
57
+ }
58
+ return { stage, class: 'unknown' };
59
+ }
@@ -94,7 +94,7 @@ export interface CacheKeepManagerOptions<M> {
94
94
  maxBytes?: number;
95
95
  /** One deadline for credential resolution and the send. Default 30 s. */
96
96
  warmTimeoutMs?: number;
97
- /** Delay after a failed warm, fixed or by consecutive failures. Default 10 minutes. */
97
+ /** Override failure delays, fixed or by consecutive failures. Defaults to expiry-bounded transient retries, otherwise 10 minutes. */
98
98
  backoffMs?: CacheKeepBackoff;
99
99
  /** The configured clock window; undefined means always warm. Read on every call. */
100
100
  getWindow?: () => CacheKeepWindow | undefined;
@@ -160,9 +160,11 @@ export interface CacheKeepStatus {
160
160
  * session stopped using (`sustain` lifts only the main-session idle cap, not
161
161
  * the lifetime); the target-count and byte caps evict the least recently
162
162
  * touched target; a per-target warm cap retires short-lived sessions; and a
163
- * failed warm backs that target off without touching the others. A retry
164
- * after a failure is sent only while the lifetime lasts, so a backoff that
165
- * runs past it retires the target instead.
163
+ * failed warm backs that target off without touching the others. Default
164
+ * transient retries use 20/40/60-second delays, clipped to the last safe start
165
+ * (expiry minus the warm timeout and 5 seconds). Only default-policy retries
166
+ * observe that deadline: first attempts and explicit backoff policies retain
167
+ * their existing lead-time scheduling, bounded by the cache lifetime.
166
168
  */
167
169
  export declare class CacheKeepManager<M = undefined> {
168
170
  private readonly targets;
@@ -218,6 +220,10 @@ export declare class CacheKeepManager<M = undefined> {
218
220
  private isCurrent;
219
221
  private view;
220
222
  private fail;
223
+ private lastRetryStart;
224
+ private canRetry;
225
+ private clearRetry;
226
+ private scheduleRetry;
221
227
  private warm;
222
228
  private idleDefault;
223
229
  private pruneStale;
@@ -1,4 +1,5 @@
1
1
  import { combineAbortSignals } from '../util/any-signal.js';
2
+ import { classifyFailure } from './failure.js';
2
3
  import { isWithinCacheKeepWindow } from './window.js';
3
4
  const DEFAULT_TTL_MS = 5 * 60_000;
4
5
  const DEFAULT_MAX_IDLE_WARM_MS = 60 * 60_000;
@@ -8,14 +9,14 @@ const DEFAULT_MAX_TARGETS = 32;
8
9
  const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
9
10
  const DEFAULT_WARM_TIMEOUT_MS = 30_000;
10
11
  const DEFAULT_BACKOFF_MS = 10 * 60_000;
12
+ const TRANSIENT_RETRY_STEP_MS = 20_000;
13
+ const TRANSIENT_RETRY_MAX_MS = 60_000;
14
+ const EXPIRY_SAFETY_MS = 5_000;
11
15
  function positive(value, fallback) {
12
16
  return typeof value === 'number' && Number.isFinite(value) && value > 0
13
17
  ? value
14
18
  : fallback;
15
19
  }
16
- function errorMessage(error) {
17
- return error instanceof Error ? error.message : String(error);
18
- }
19
20
  /**
20
21
  * Keeps idle prompt caches warm: one target per session holding the latest
21
22
  * request body, replayed just before the provider's cache would expire.
@@ -29,9 +30,11 @@ function errorMessage(error) {
29
30
  * session stopped using (`sustain` lifts only the main-session idle cap, not
30
31
  * the lifetime); the target-count and byte caps evict the least recently
31
32
  * touched target; a per-target warm cap retires short-lived sessions; and a
32
- * failed warm backs that target off without touching the others. A retry
33
- * after a failure is sent only while the lifetime lasts, so a backoff that
34
- * runs past it retires the target instead.
33
+ * failed warm backs that target off without touching the others. Default
34
+ * transient retries use 20/40/60-second delays, clipped to the last safe start
35
+ * (expiry minus the warm timeout and 5 seconds). Only default-policy retries
36
+ * observe that deadline: first attempts and explicit backoff policies retain
37
+ * their existing lead-time scheduling, bounded by the cache lifetime.
35
38
  */
36
39
  export class CacheKeepManager {
37
40
  targets = new Map();
@@ -71,7 +74,7 @@ export class CacheKeepManager {
71
74
  this.maxTargets = positive(options.maxTargets, DEFAULT_MAX_TARGETS);
72
75
  this.maxBytes = positive(options.maxBytes, DEFAULT_MAX_BYTES);
73
76
  this.warmTimeoutMs = positive(options.warmTimeoutMs, DEFAULT_WARM_TIMEOUT_MS);
74
- this.backoff = options.backoffMs ?? DEFAULT_BACKOFF_MS;
77
+ this.backoff = options.backoffMs;
75
78
  this.getWindow = options.getWindow;
76
79
  this.getSustain = options.getSustain;
77
80
  this.setIntervalImpl = options.setIntervalImpl ?? globalThis.setInterval;
@@ -163,7 +166,7 @@ export class CacheKeepManager {
163
166
  this.startedAt = this.now();
164
167
  this.timer = this.setIntervalImpl(() => {
165
168
  void this.tick().catch((error) => {
166
- this.log?.warn('cachekeep tick failed', { error: errorMessage(error) });
169
+ this.log?.warn('cachekeep tick failed', classifyFailure(error, 'send'));
167
170
  });
168
171
  }, this.tickIntervalMs);
169
172
  if (typeof this.timer === 'object' && 'unref' in this.timer) {
@@ -185,6 +188,8 @@ export class CacheKeepManager {
185
188
  this.timer = null;
186
189
  }
187
190
  this.startedAt = null;
191
+ for (const target of this.targets.values())
192
+ this.clearRetry(target);
188
193
  this.targets.clear();
189
194
  this.totalBytes = 0;
190
195
  this.log?.debug('cachekeep stopped');
@@ -247,17 +252,18 @@ export class CacheKeepManager {
247
252
  if (window && !isWithinCacheKeepWindow(window, new Date(this.now()))) {
248
253
  return;
249
254
  }
250
- const now = this.now();
251
- const leadBound = now + this.leadMs;
252
255
  for (const [sessionKey, target] of [...this.targets]) {
253
256
  if (this.disposed)
254
257
  return;
255
258
  if (this.targets.get(sessionKey) !== target)
256
259
  continue;
260
+ const now = this.now();
257
261
  if (target.backoffUntil !== undefined && now < target.backoffUntil) {
258
262
  continue;
259
263
  }
260
- if (target.cacheExpiresAt > leadBound)
264
+ if (target.cacheExpiresAt > now + this.leadMs)
265
+ continue;
266
+ if (!this.canRetry(target))
261
267
  continue;
262
268
  await this.warm(sessionKey, target);
263
269
  }
@@ -293,26 +299,72 @@ export class CacheKeepManager {
293
299
  ttlMs: target.ttlMs,
294
300
  };
295
301
  }
296
- fail(sessionKey, target, message, fields = {}) {
302
+ fail(sessionKey, target, message, failure, transient = false, status) {
297
303
  if (!this.isCurrent(sessionKey, target))
298
304
  return;
299
305
  target.failures += 1;
300
- const delay = typeof this.backoff === 'function'
306
+ const now = this.now();
307
+ let delay = typeof this.backoff === 'function'
301
308
  ? this.backoff({ sessionKey, failures: target.failures })
302
- : this.backoff;
309
+ : (this.backoff ?? DEFAULT_BACKOFF_MS);
310
+ const deadline = this.lastRetryStart(target);
311
+ const fastRetry = this.backoff === undefined && transient && now < deadline;
312
+ if (fastRetry) {
313
+ delay = Math.min(TRANSIENT_RETRY_STEP_MS * target.failures, TRANSIENT_RETRY_MAX_MS, deadline - now);
314
+ }
303
315
  target.backoffUntil =
304
- this.now() + (Number.isFinite(delay) && delay > 0 ? delay : 0);
316
+ now + (Number.isFinite(delay) && delay > 0 ? delay : 0);
317
+ this.clearRetry(target);
318
+ if (fastRetry)
319
+ this.scheduleRetry(sessionKey, target, delay);
305
320
  this.log?.warn(message, {
306
321
  sessionKey,
307
322
  accountId: target.accountId,
308
323
  failures: target.failures,
309
324
  backoffUntil: target.backoffUntil,
310
- ...fields,
325
+ ...failure,
326
+ ...(status !== undefined && { status }),
311
327
  });
312
328
  }
329
+ lastRetryStart(target) {
330
+ return target.cacheExpiresAt - this.warmTimeoutMs - EXPIRY_SAFETY_MS;
331
+ }
332
+ canRetry(target) {
333
+ return (this.backoff !== undefined ||
334
+ target.failures === 0 ||
335
+ this.now() <= this.lastRetryStart(target));
336
+ }
337
+ clearRetry(target) {
338
+ if (target.retryTimer === undefined)
339
+ return;
340
+ this.clearIntervalImpl(target.retryTimer);
341
+ target.retryTimer = undefined;
342
+ }
343
+ scheduleRetry(sessionKey, target, delay) {
344
+ // Use the same injected timer pair as the regular tick, but clear this
345
+ // interval before dispatch so it acts as a one-shot retry timer.
346
+ target.retryTimer = this.setIntervalImpl(() => {
347
+ this.clearRetry(target);
348
+ return (async () => {
349
+ // A different target can still be warming. Wait for that tick before
350
+ // rechecking eligibility, rather than losing this wake-up to coalescing.
351
+ await this.tickPromise;
352
+ if (this.isCurrent(sessionKey, target))
353
+ await this.tick();
354
+ })().catch((error) => {
355
+ this.log?.warn('cachekeep tick failed', classifyFailure(error, 'send'));
356
+ });
357
+ }, delay);
358
+ if (typeof target.retryTimer === 'object' && 'unref' in target.retryTimer) {
359
+ target.retryTimer.unref();
360
+ }
361
+ }
313
362
  async warm(sessionKey, target) {
314
363
  if (this.retireIfExpired(sessionKey, target))
315
364
  return;
365
+ if (!this.canRetry(target))
366
+ return;
367
+ this.clearRetry(target);
316
368
  const view = this.view(sessionKey, target);
317
369
  if (this.adapter.activeAccount) {
318
370
  let active;
@@ -320,9 +372,7 @@ export class CacheKeepManager {
320
372
  active = await this.adapter.activeAccount(sessionKey, view);
321
373
  }
322
374
  catch (error) {
323
- this.fail(sessionKey, target, 'cachekeep skip (active account unknown)', {
324
- error: errorMessage(error),
325
- });
375
+ this.fail(sessionKey, target, 'cachekeep skip (active account unknown)', classifyFailure(error, 'authorization'), true);
326
376
  return;
327
377
  }
328
378
  if (!this.isCurrent(sessionKey, target))
@@ -342,15 +392,15 @@ export class CacheKeepManager {
342
392
  body = await this.adapter.buildBody(view);
343
393
  }
344
394
  catch (error) {
345
- this.fail(sessionKey, target, 'cachekeep skip (replay body unbuildable)', {
346
- error: errorMessage(error),
347
- });
395
+ this.fail(sessionKey, target, 'cachekeep skip (replay body unbuildable)', classifyFailure(error, 'authorization'));
348
396
  return;
349
397
  }
350
398
  if (!this.isCurrent(sessionKey, target))
351
399
  return;
352
400
  if (this.retireIfExpired(sessionKey, target))
353
401
  return;
402
+ if (!this.canRetry(target))
403
+ return;
354
404
  const combined = combineAbortSignals([
355
405
  AbortSignal.timeout(this.warmTimeoutMs),
356
406
  this.abortController.signal,
@@ -358,16 +408,21 @@ export class CacheKeepManager {
358
408
  const signal = combined.signal;
359
409
  let response;
360
410
  let text = '';
411
+ let stage = 'send';
412
+ let status;
361
413
  try {
362
414
  response = await this.adapter.send({ target: view, body, signal });
363
- // Drain the body so the connection is released; its text is only
364
- // diagnostic.
365
- text = await response.text().catch(() => '');
415
+ stage = 'response';
416
+ status = response.status;
417
+ // Drain the body to release the connection and let the adapter read usage.
418
+ text = await response.text();
366
419
  }
367
420
  catch (error) {
368
- this.fail(sessionKey, target, 'cachekeep failed', {
369
- error: errorMessage(error),
370
- });
421
+ this.fail(sessionKey, target, 'cachekeep failed', classifyFailure(error, stage, status), status === undefined ||
422
+ (status >= 200 && status < 300) ||
423
+ status === 408 ||
424
+ status === 429 ||
425
+ status >= 500, status);
371
426
  return;
372
427
  }
373
428
  finally {
@@ -376,10 +431,9 @@ export class CacheKeepManager {
376
431
  if (!this.isCurrent(sessionKey, target))
377
432
  return;
378
433
  if (!response.ok) {
379
- this.fail(sessionKey, target, 'cachekeep failed', {
380
- status: response.status,
381
- responseBody: text.slice(0, 600),
382
- });
434
+ this.fail(sessionKey, target, 'cachekeep failed', classifyFailure(undefined, 'response', response.status), response.status === 408 ||
435
+ response.status === 429 ||
436
+ response.status >= 500, response.status);
383
437
  return;
384
438
  }
385
439
  let usage;
@@ -393,6 +447,7 @@ export class CacheKeepManager {
393
447
  target.cacheExpiresAt = now + target.ttlMs;
394
448
  target.lastWarmedAt = now;
395
449
  target.backoffUntil = undefined;
450
+ this.clearRetry(target);
396
451
  target.failures = 0;
397
452
  target.warmCount += 1;
398
453
  this.log?.debug('cachekeep fired', {
@@ -452,6 +507,7 @@ export class CacheKeepManager {
452
507
  const target = this.targets.get(sessionKey);
453
508
  if (!target)
454
509
  return false;
510
+ this.clearRetry(target);
455
511
  this.totalBytes -= target.bodyBytes;
456
512
  this.targets.delete(sessionKey);
457
513
  return true;
@@ -2,7 +2,7 @@ import { AsyncResource } from 'node:async_hooks';
2
2
  import { randomUUID } from 'node:crypto';
3
3
  import { isDeepStrictEqual } from 'node:util';
4
4
  import { mergeAccessState } from './merge-laws.js';
5
- import { createLimitsNamespace, pruneLimitsNamespace, timedMarkKeyId, } from './namespace.js';
5
+ import { clearTombstoneId, createLimitsNamespace, pruneLimitsNamespace, timedMarkKeyId, tombstoneCoversCause, } from './namespace.js';
6
6
  const detached = new AsyncResource('common-auth-limits-recovery');
7
7
  /** Readers never join the write lock; notify them after a detached repair lands. */
8
8
  export class EnvelopeRepair {
@@ -82,6 +82,7 @@ export class EnvelopeHistory {
82
82
  present.revision < seen.revision ||
83
83
  seen.tombstones.some((clear) => clear.revision > present.lowWatermark &&
84
84
  !present.tombstones.some((current) => timedMarkKeyId(current.key) === timedMarkKeyId(clear.key) &&
85
+ tombstoneCoversCause(current, clear.cause) &&
85
86
  current.revision >= clear.revision)));
86
87
  }
87
88
  /** Preview a restrictive merge, or apply it against the envelope under the write lock. */
@@ -111,7 +112,7 @@ export class EnvelopeHistory {
111
112
  highest = Math.max(highest, entry.baseRevision, entry.committedRevision);
112
113
  }
113
114
  for (const clear of source.tombstones) {
114
- const id = timedMarkKeyId(clear.key);
115
+ const id = clearTombstoneId(clear);
115
116
  const old = tombstones.get(id);
116
117
  if (!old || old.revision < clear.revision)
117
118
  tombstones.set(id, clear);
@@ -19,7 +19,12 @@ export interface NamespaceMark {
19
19
  export interface ClearTombstone {
20
20
  readonly key: TimedMarkKey;
21
21
  readonly revision: number;
22
+ /** Omitted by legacy writers and all-cause clears; only stored enum values belong here. */
23
+ readonly cause?: LimitMarkCause;
22
24
  }
25
+ /** An absent cause is the conservative all-cause fence used by older writers. */
26
+ export declare function tombstoneCoversCause(clear: ClearTombstone, cause: LimitMarkCause | undefined): boolean;
27
+ export declare function clearTombstoneId(clear: ClearTombstone): string;
23
28
  export interface CommittedOperation {
24
29
  readonly producerId: string;
25
30
  readonly operationId: string;
@@ -2,6 +2,18 @@ import { validateIdentityFence } from './identity.js';
2
2
  import { mergeAccessState, mergeTimedMarkEntries } from './merge-laws.js';
3
3
  import { sameAccount } from './request-history.js';
4
4
  export const LIMITS_HISTORY_BOUND = 1024;
5
+ function storedCause(cause) {
6
+ return cause === 'rate-limit' || cause === 'payment-balance'
7
+ ? cause
8
+ : undefined;
9
+ }
10
+ /** An absent cause is the conservative all-cause fence used by older writers. */
11
+ export function tombstoneCoversCause(clear, cause) {
12
+ return storedCause(clear.cause) === undefined || clear.cause === cause;
13
+ }
14
+ export function clearTombstoneId(clear) {
15
+ return JSON.stringify([timedMarkKeyId(clear.key), storedCause(clear.cause)]);
16
+ }
5
17
  export function createLimitsNamespace(namespace, generation) {
6
18
  return {
7
19
  schemaVersion: 1,
@@ -40,9 +52,21 @@ function operationId(op) {
40
52
  }
41
53
  /** Apply tombstones before compacting them; the watermark then fences delayed commands. */
42
54
  export function pruneLimitsNamespace(snapshot, now) {
43
- const clears = new Map(snapshot.tombstones.map((t) => [timedMarkKeyId(t.key), t.revision]));
55
+ const clears = new Map();
56
+ for (const clear of snapshot.tombstones) {
57
+ const id = timedMarkKeyId(clear.key);
58
+ const list = clears.get(id);
59
+ if (list)
60
+ list.push(clear);
61
+ else
62
+ clears.set(id, [clear]);
63
+ }
44
64
  const marks = snapshot.marks.flatMap((mark) => {
45
- const entries = mergeTimedMarkEntries(mark.mergeLaw, mark.entries, now, clears.get(timedMarkKeyId(mark.key)));
65
+ const fences = clears.get(timedMarkKeyId(mark.key));
66
+ const entries = mergeTimedMarkEntries(mark.mergeLaw, fences
67
+ ? mark.entries.filter((entry) => !fences.some((clear) => tombstoneCoversCause(clear, entry.cause) &&
68
+ entry.baseRevision < clear.revision))
69
+ : mark.entries, now);
46
70
  return entries.length ? [{ ...mark, entries }] : [];
47
71
  });
48
72
  let lowWatermark = snapshot.lowWatermark;
@@ -114,8 +138,9 @@ export function applyLimitsCommands(initial, commands, context) {
114
138
  const key = { account, scope: command.scope, window: command.window };
115
139
  const id = timedMarkKeyId(key);
116
140
  const previous = marks.find((m) => timedMarkKeyId(m.key) === id);
117
- const clear = tombstones.find((t) => timedMarkKeyId(t.key) === id);
118
- if (clear && command.baseRevision < clear.revision) {
141
+ if (tombstones.some((clear) => command.baseRevision < clear.revision &&
142
+ tombstoneCoversCause(clear, command.cause) &&
143
+ timedMarkKeyId(clear.key) === id)) {
119
144
  reject('cleared');
120
145
  continue;
121
146
  }
@@ -135,12 +160,13 @@ export function applyLimitsCommands(initial, commands, context) {
135
160
  ? { cause: command.cause }
136
161
  : {}),
137
162
  },
138
- ], context.now, clear?.revision);
163
+ ], context.now);
139
164
  marks = marks.filter((m) => timedMarkKeyId(m.key) !== id);
140
165
  if (entries.length)
141
166
  marks.push({ key, mergeLaw: command.mergeLaw, entries });
142
167
  }
143
168
  else if (command.type === 'clear') {
169
+ const cause = storedCause(command.cause);
144
170
  const keys = command.keys
145
171
  .map((key) => ({ ...key, account }))
146
172
  .filter((key) => command.cause === undefined ||
@@ -155,10 +181,17 @@ export function applyLimitsCommands(initial, commands, context) {
155
181
  continue;
156
182
  }
157
183
  marks = marks.filter((m) => !ids.has(timedMarkKeyId(m.key)));
158
- tombstones = tombstones.filter((t) => !ids.has(timedMarkKeyId(t.key)));
184
+ // Keep earlier fences for other causes, including an earlier all-cause clear.
185
+ // Replacing them would either lose a fence or extend it to unrelated evidence.
186
+ tombstones = tombstones.filter((t) => !ids.has(timedMarkKeyId(t.key)) ||
187
+ (cause !== undefined && t.cause !== cause));
159
188
  // A clear enumerates covered keys, not all scopes on the account.
160
189
  for (const key of new Map(keys.map((k) => [timedMarkKeyId(k), k])).values()) {
161
- tombstones.push({ key, revision });
190
+ tombstones.push({
191
+ key,
192
+ revision,
193
+ ...(cause === undefined ? {} : { cause }),
194
+ });
162
195
  }
163
196
  }
164
197
  else {
@@ -30,7 +30,8 @@ export declare function applyHeaderEdits(target: Record<string, string>, edits:
30
30
  * - `retry` asks the host to retry at once when an account was refused
31
31
  * before any output and `chooseAccount` names another account for the
32
32
  * next attempt, keeps the host's decision when the refused account was the
33
- * last one that can serve, and refuses to retry once output has started.
33
+ * last one that can serve. After output, only a witnessed HTTP read failure
34
+ * with adapter-approved same-account continuation can keep the host's retry.
34
35
  *
35
36
  * Attribution. A send belongs to the attempt named by the mark
36
37
  * `model.request` left on it, so several attempts of one session and kind
@@ -101,7 +101,8 @@ function applyHeaderEditsTo(target, edits) {
101
101
  * - `retry` asks the host to retry at once when an account was refused
102
102
  * before any output and `chooseAccount` names another account for the
103
103
  * next attempt, keeps the host's decision when the refused account was the
104
- * last one that can serve, and refuses to retry once output has started.
104
+ * last one that can serve. After output, only a witnessed HTTP read failure
105
+ * with adapter-approved same-account continuation can keep the host's retry.
105
106
  *
106
107
  * Attribution. A send belongs to the attempt named by the mark
107
108
  * `model.request` left on it, so several attempts of one session and kind
@@ -471,6 +472,12 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
471
472
  await inChoiceOrder(scope.sessionID, () => releaseSameAccount(sameAccount));
472
473
  assertActive();
473
474
  }
475
+ if (sameAccount?.continuation &&
476
+ (!sameRoute || mixed(scope.sessionID))) {
477
+ if (sameRoute)
478
+ await inChoiceOrder(scope.sessionID, () => releaseSameAccount(sameAccount));
479
+ throw noAccount(scope);
480
+ }
474
481
  const choice = sameRoute
475
482
  ? sameAccount.accountId
476
483
  : matches && wake === undefined
@@ -796,7 +803,11 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
796
803
  error: describe(error),
797
804
  })));
798
805
  }
799
- response = new Response(trackBody(body, (error) => finish(rec, error)), {
806
+ response = new Response(trackBody(body, (error) => {
807
+ if (error?.reason === 'failed')
808
+ rec.httpReadFailed = true;
809
+ finish(rec, error);
810
+ }), {
800
811
  status: original.status,
801
812
  statusText: original.statusText,
802
813
  headers: original.headers,
@@ -936,9 +947,38 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
936
947
  const checkRetryActive = assertActive;
937
948
  const retrySameAccount = adapter.retrySameAccount?.bind(adapter);
938
949
  const handle = rec.attempt;
950
+ const afterOutput = rec.outputStarted;
951
+ if (afterOutput &&
952
+ rec.httpReadFailed &&
953
+ retrySameAccount &&
954
+ handle &&
955
+ !mixed(draft.sessionID)) {
956
+ if (!rec.limit) {
957
+ const signal = adapter.limitFromError?.(draft.error, handle);
958
+ if (signal)
959
+ noteLimit(rec, signal, 'error');
960
+ }
961
+ if (rec.ended)
962
+ await rec.ended;
963
+ if (rec.limit)
964
+ await rec.limit.delivered;
965
+ checkRetryActive();
966
+ }
967
+ // The host drops read-operation metadata from its retry error. Only
968
+ // our attributed body reader can prove a read failed; wording cannot.
969
+ const canContinue = () => rec.httpReadFailed === true &&
970
+ draft.error.type === 'provider.transport' &&
971
+ hostDecision.retry &&
972
+ hostRetryLimit - draft.attempt >= 1 &&
973
+ !rec.limit &&
974
+ !(rec.status !== undefined && rec.status >= 400) &&
975
+ !(draft.error.status !== undefined && draft.error.status >= 400) &&
976
+ !handle?.reboundFrom &&
977
+ !vetoed() &&
978
+ !mixed(draft.sessionID);
939
979
  if (retrySameAccount &&
940
980
  handle &&
941
- !rec.outputStarted &&
981
+ (!afterOutput || canContinue()) &&
942
982
  (!vetoed() || mixed(draft.sessionID)) &&
943
983
  !rec.sameAccountRetry) {
944
984
  if (rec.ended)
@@ -951,7 +991,8 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
951
991
  const active = () => attempts.has(rec.id) &&
952
992
  rec.accountId === accountId &&
953
993
  pickForRetry(draft.sessionID) === rec &&
954
- !rec.outputStarted &&
994
+ rec.outputStarted === afterOutput &&
995
+ (!afterOutput || canContinue()) &&
955
996
  (!vetoed() || mixed(draft.sessionID)) &&
956
997
  (!ownership ||
957
998
  latestTransportOwned.get(draft.sessionID) === true);
@@ -964,6 +1005,9 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
964
1005
  error: draft.error,
965
1006
  attempt: draft.attempt,
966
1007
  ...(rec.limit ? { limit: rec.limit.signal } : {}),
1008
+ ...(afterOutput
1009
+ ? { continuation: 'interrupted-read' }
1010
+ : {}),
967
1011
  };
968
1012
  let result;
969
1013
  try {
@@ -979,7 +1023,11 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
979
1023
  checkRetryActive();
980
1024
  return false;
981
1025
  }
982
- const sameAccount = { accountId: result.accountId, input };
1026
+ const sameAccount = {
1027
+ accountId: result.accountId,
1028
+ input,
1029
+ ...(afterOutput ? { continuation: true } : {}),
1030
+ };
983
1031
  try {
984
1032
  checkRetryActive();
985
1033
  }
@@ -1017,7 +1065,9 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
1017
1065
  sameAccount,
1018
1066
  });
1019
1067
  rec.judged = true;
1020
- draft.decision = { retry: true, delay: 0 };
1068
+ draft.decision = afterOutput
1069
+ ? hostDecision
1070
+ : { retry: true, delay: 0 };
1021
1071
  return true;
1022
1072
  });
1023
1073
  checkRetryActive();
@@ -1027,7 +1077,7 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
1027
1077
  accountId: rec.accountId,
1028
1078
  kind: rec.scope.kind,
1029
1079
  attempt: draft.attempt,
1030
- reason: 'same-account',
1080
+ reason: afterOutput ? 'continue-same-account' : 'same-account',
1031
1081
  hostDecision,
1032
1082
  decision: draft.decision,
1033
1083
  handle: rec.attempt,
@@ -1082,8 +1132,7 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
1082
1132
  reason = 'no-account';
1083
1133
  }
1084
1134
  else if (rec.outputStarted) {
1085
- // The user has already seen part of this answer; a retry would
1086
- // send it again.
1135
+ // Only the guarded same-account path above may continue partial output.
1087
1136
  decision = { retry: false };
1088
1137
  reason = 'output-started';
1089
1138
  }
@@ -221,6 +221,14 @@ export interface SameAccountRetryInput extends AccountRequest {
221
221
  * limitFromError is not called before this callback in a mixed session.
222
222
  */
223
223
  readonly limit?: LimitSignal;
224
+ /**
225
+ * Set only when output had already started and our own HTTP body reader saw
226
+ * the read fail, so the host is offering to continue the step rather than
227
+ * retry it. The adapter approves by returning the same accountId when the
228
+ * account and identity are still usable; it has no prepared recovery state
229
+ * to consume, and `limit` is always absent here.
230
+ */
231
+ readonly continuation?: 'interrupted-read';
224
232
  }
225
233
  /** Request an immediate retry; a different account ID is ignored. */
226
234
  export interface SameAccountRetryResult {
@@ -437,7 +445,7 @@ export interface OpenCode2AuthAdapter<Q = unknown, A = unknown, Choice extends C
437
445
  * A different accountId is ignored. Never move a routing pin or select another
438
446
  * account here: use chooseAccount for failover and holds.
439
447
  *
440
- * Runs only for an attributable attempt before output, and, when gated, only
448
+ * Runs for an attributable attempt before output, and, when gated, only
441
449
  * while the latest transport is owned. Unlike failover and holds, it also runs
442
450
  * in mixed-ownership sessions. The next matching owned request skips selection
443
451
  * and calls accountHeaders again for this account, so newer credentials or a
@@ -449,6 +457,12 @@ export interface OpenCode2AuthAdapter<Q = unknown, A = unknown, Choice extends C
449
457
  * No choice was committed through chooseAccount; unused recovery state is
450
458
  * released through dropSameAccountRetry instead of dropChoice.
451
459
  * Errors are logged and treated as declining the retry.
460
+ * After output it also gates a host-approved continuation when the attributed
461
+ * HTTP body reader failed, no limit or veto exists, ownership is unmixed and
462
+ * the host retry budget remains. The host's decision and delay are preserved;
463
+ * the callback must decline if the account is no longer usable or its identity
464
+ * changed. Native WebSocket failures and clean but incomplete streams lack
465
+ * the structured host error fields needed to allow this exception.
452
466
  */
453
467
  retrySameAccount?(input: SameAccountRetryInput): Promise<SameAccountRetryResult | undefined> | SameAccountRetryResult | undefined;
454
468
  /**
@@ -526,7 +540,9 @@ export interface InstallOpenCode2AuthOptions {
526
540
  *
527
541
  * - `reroute`: refused for a limit before any output, and `chooseAccount`
528
542
  * named another account for the next attempt, so the host retries at once;
529
- * - `output-started`: output had reached the user, so no retry;
543
+ * - `output-started`: output reached the user without a safe continuation, so no retry;
544
+ * - `continue-same-account`: a witnessed HTTP read failure after output, with
545
+ * adapter-approved identity preservation; keeps the host's continuation and delay;
530
546
  * - `no-account`: the attempt had no account, so no retry;
531
547
  * - `host-decides-last-account`: refused for a limit before any output, but
532
548
  * no other account can serve the next attempt, so the host's own decision
@@ -541,7 +557,7 @@ export interface InstallOpenCode2AuthOptions {
541
557
  * attributed safely (ambiguous attempts or mixed ownership in a gated
542
558
  * session), so the host's decision stands.
543
559
  */
544
- export type RetryReason = 'reroute' | 'hold' | 'wait-then-reselect' | 'adapter-veto' | 'same-account' | 'output-started' | 'no-account' | 'host-decides-last-account' | 'host-decides';
560
+ export type RetryReason = 'reroute' | 'hold' | 'wait-then-reselect' | 'adapter-veto' | 'same-account' | 'continue-same-account' | 'output-started' | 'no-account' | 'host-decides-last-account' | 'host-decides';
545
561
  /**
546
562
  * The hook that picked an account. Normally `model.request`; a transport hook
547
563
  * picks only when the host skipped `model.request` for that request, which a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cortexkit/common-auth",
3
- "version": "0.35.0",
3
+ "version": "0.37.0",
4
4
  "description": "Shared code for the CortexKit auth plugins: account pool, quota and routing, commands and auth menu, OpenCode 2 hooks, Claustrum custody, and plumbing (loopback RPC, file locks, logger, sidebar state, TUI preferences and build).",
5
5
  "license": "MIT",
6
6
  "repository": {