@cortexkit/common-auth 0.30.0 → 0.32.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,3 +1,4 @@
1
+ import { channel } from 'node:diagnostics_channel';
1
2
  import { ClaustrumCredentialError, } from '@cortexkit/claustrum-client';
2
3
  import { createLogger } from '../logger/index.js';
3
4
  import { ClaustrumUnreachableError, classifyVaultFailure, } from './availability.js';
@@ -27,6 +28,8 @@ function scopedRetryReason(served, current) {
27
28
  return 'rotated';
28
29
  }
29
30
  const defaultLogger = createLogger('claustrum');
31
+ // Opt-in diagnostics let tests retain wait phases without logging each vault read.
32
+ const phaseDiagnostics = channel('common-auth.claustrum.phases');
30
33
  /**
31
34
  * Decide whether a request that got a 401 should retry with the freshly
32
35
  * re-authorized receipt, and log the decision. The vault can refresh a
@@ -280,6 +283,11 @@ export class ClaustrumScopedCustody {
280
283
  }
281
284
  async #token(signal) {
282
285
  this.#check(signal);
286
+ if (phaseDiagnostics.hasSubscribers)
287
+ phaseDiagnostics.publish({
288
+ logger: this.#logger,
289
+ phase: 'token read begin',
290
+ });
283
291
  const pending = this.#readToken();
284
292
  this.#tokenReads.add(pending);
285
293
  let value;
@@ -288,6 +296,11 @@ export class ClaustrumScopedCustody {
288
296
  }
289
297
  finally {
290
298
  this.#tokenReads.delete(pending);
299
+ if (phaseDiagnostics.hasSubscribers)
300
+ phaseDiagnostics.publish({
301
+ logger: this.#logger,
302
+ phase: 'token read end',
303
+ });
291
304
  }
292
305
  this.#check(signal);
293
306
  if (!/^[0-9a-f]{64}$/.test(value.token) ||
@@ -359,6 +372,11 @@ export class ClaustrumScopedCustody {
359
372
  this.#kept.clear();
360
373
  throw error;
361
374
  }
375
+ if (phaseDiagnostics.hasSubscribers)
376
+ phaseDiagnostics.publish({
377
+ logger: this.#logger,
378
+ phase: 'list scoped begin',
379
+ });
362
380
  try {
363
381
  inventory = await this.#call(() => this.#client.listScoped(token), signal);
364
382
  }
@@ -366,6 +384,13 @@ export class ClaustrumScopedCustody {
366
384
  this.listFailed(error);
367
385
  throw error;
368
386
  }
387
+ finally {
388
+ if (phaseDiagnostics.hasSubscribers)
389
+ phaseDiagnostics.publish({
390
+ logger: this.#logger,
391
+ phase: 'list scoped end',
392
+ });
393
+ }
369
394
  const skipped = [];
370
395
  const refused = [];
371
396
  let notMine = 0;
@@ -11,6 +11,7 @@
11
11
  // different processes already share, plus the base-view rule, so a commit
12
12
  // never replaces a view another process committed after this hub listed.
13
13
  import { createHash } from 'node:crypto';
14
+ import { channel } from 'node:diagnostics_channel';
14
15
  import { readdir, stat } from 'node:fs/promises';
15
16
  import { dirname, join, resolve } from 'node:path';
16
17
  import { createLogger } from '../logger/index.js';
@@ -766,7 +767,25 @@ export class ClaustrumDiscoveryHub {
766
767
  throw base;
767
768
  // A member's first roster under this key carries the declines and
768
769
  // order of its newest roster under an older key.
769
- const seed = base.file ? undefined : await this.#seed(entry);
770
+ let seed;
771
+ if (!base.file) {
772
+ const phaseDiagnostics = channel('common-auth.claustrum.phases');
773
+ if (phaseDiagnostics.hasSubscribers)
774
+ phaseDiagnostics.publish({
775
+ logger: this.#logger,
776
+ phase: `seed read ${entry.provider} begin`,
777
+ });
778
+ try {
779
+ seed = await this.#seed(entry);
780
+ }
781
+ finally {
782
+ if (phaseDiagnostics.hasSubscribers)
783
+ phaseDiagnostics.publish({
784
+ logger: this.#logger,
785
+ phase: `seed read ${entry.provider} end`,
786
+ });
787
+ }
788
+ }
770
789
  const roster = await refreshVaultRoster({
771
790
  path: entry.path,
772
791
  custody: { discover: async () => share },
@@ -443,6 +443,12 @@ export class InsulaQuotaSource {
443
443
  ...(typeof entry.source === 'string' && { source: entry.source }),
444
444
  },
445
445
  };
446
+ // Kept usage must not trigger a provider poll after a non-local failure.
447
+ // Only an explicitly local failure permits fallback; unknown causes do not.
448
+ if (entry.stale !== undefined &&
449
+ (!record(entry.stale) ||
450
+ entry.stale.class !== 'local_source_unavailable'))
451
+ return { miss: 'upstream-failed', reading };
446
452
  return now >= fetchedAt + MAX_AGE || entry.stale !== undefined
447
453
  ? { miss: 'stale', reading }
448
454
  : { reading };
@@ -0,0 +1,86 @@
1
+ import type { RGBA } from '@opentui/core';
2
+ import type { JSX } from '@opentui/solid';
3
+ import type { QuotaWindowPart } from '../quota/format.js';
4
+ import type { ProjectedQuota } from '../quota/projection.js';
5
+ export type Tone = 'text' | 'textMuted' | 'accent' | 'success' | 'warning' | 'error';
6
+ export type SidebarTheme = Readonly<Partial<Record<Tone | 'background' | 'borderActive', RGBA | string | undefined>>>;
7
+ export interface SidebarAppearance {
8
+ barWidth: number;
9
+ barFilledChar: string;
10
+ barEmptyChar: string;
11
+ warnThreshold: number;
12
+ errorThreshold: number;
13
+ }
14
+ export interface PaceView {
15
+ text: string;
16
+ tone: Tone;
17
+ /** The elapsed-window percentage, not the difference from usage. */
18
+ overlay?: {
19
+ kind: 'reserve' | 'deficit';
20
+ percent: number;
21
+ };
22
+ }
23
+ export interface QuotaGroupView {
24
+ title?: string;
25
+ rows: readonly {
26
+ part: QuotaWindowPart;
27
+ pace?: PaceView;
28
+ }[];
29
+ }
30
+ export interface AccountView {
31
+ id: string;
32
+ label: string;
33
+ titleSuffix?: string;
34
+ status: {
35
+ text: string;
36
+ tone: Tone;
37
+ };
38
+ blocked: boolean;
39
+ indicatorTone: Tone;
40
+ quota: ProjectedQuota | undefined;
41
+ groups: readonly QuotaGroupView[];
42
+ emptyQuotaText?: {
43
+ expanded: string;
44
+ collapsed: string;
45
+ };
46
+ /** Presentation decided by the plugin, never inferred from status or freshness. */
47
+ collapsed?: {
48
+ quotaTone?: Tone;
49
+ muted?: boolean;
50
+ };
51
+ }
52
+ export interface SidebarFrameProps {
53
+ header: {
54
+ badge: string;
55
+ version?: string;
56
+ };
57
+ accounts: readonly AccountView[];
58
+ theme?: SidebarTheme;
59
+ appearance: SidebarAppearance;
60
+ showQuota: boolean;
61
+ now: number;
62
+ collapsed: boolean;
63
+ onToggle: () => void;
64
+ beforeQuota?: (account: AccountView) => JSX.Element;
65
+ afterQuota?: (account: AccountView) => JSX.Element;
66
+ sections?: () => JSX.Element;
67
+ collapsedSections?: () => JSX.Element;
68
+ }
69
+ /** A heading and its plugin-owned rows, with the frame's section spacing. */
70
+ export declare function SidebarSection(props: {
71
+ title: string;
72
+ children?: JSX.Element;
73
+ }): any;
74
+ /** Keep labels whole and reserve one blank cell before an ellipsized value. */
75
+ export declare function SidebarStatRow(props: {
76
+ label: string;
77
+ value: string;
78
+ tone?: Tone;
79
+ }): any;
80
+ export declare function SidebarTextRow(props: {
81
+ text: string;
82
+ tone?: Tone;
83
+ wrapMode?: JSX.IntrinsicElements['text']['wrapMode'];
84
+ }): any;
85
+ /** Borderless, controlled presentation; host registration and provider policy stay in the plugin. */
86
+ export declare function SidebarFrame(props: SidebarFrameProps): any;
@@ -0,0 +1,327 @@
1
+ import { createContext, createMemo, createSignal, For, mergeProps, Show, useContext, } from 'solid-js';
2
+ import { formatQuota, quotaWindowParts } from '../quota/format.js';
3
+ const FrameContext = createContext();
4
+ function frameContext() {
5
+ const context = useContext(FrameContext);
6
+ if (!context)
7
+ throw new Error('Sidebar primitives must be inside SidebarFrame');
8
+ return context;
9
+ }
10
+ function displayWidth(text) {
11
+ const bun = globalThis.Bun;
12
+ return bun?.stringWidth ? bun.stringWidth(text) : Array.from(text).length;
13
+ }
14
+ function fitText(text, columns) {
15
+ if (displayWidth(text) <= columns)
16
+ return text;
17
+ if (columns < 1)
18
+ return '';
19
+ let kept = '';
20
+ let used = 0;
21
+ for (const char of text) {
22
+ const width = displayWidth(char);
23
+ if (used + width > columns - 1)
24
+ break;
25
+ kept += char;
26
+ used += width;
27
+ }
28
+ return `${kept}\u2026`;
29
+ }
30
+ /** A heading and its plugin-owned rows, with the frame's section spacing. */
31
+ export function SidebarSection(props) {
32
+ const context = frameContext();
33
+ return (<>
34
+ <box width='100%' marginTop={1}>
35
+ <text fg={context.theme.text}>
36
+ <b>{props.title}</b>
37
+ </text>
38
+ </box>
39
+ {props.children}
40
+ </>);
41
+ }
42
+ /** Keep labels whole and reserve one blank cell before an ellipsized value. */
43
+ export function SidebarStatRow(props) {
44
+ const context = frameContext();
45
+ const [width, setWidth] = createSignal(0);
46
+ let row;
47
+ const value = () => width() <= 0
48
+ ? props.value
49
+ : fitText(props.value, width() - displayWidth(props.label) - 1);
50
+ return (<box ref={(element) => {
51
+ row = element;
52
+ }} onSizeChange={() => setWidth(row?.width ?? 0)} width='100%' flexDirection='row' justifyContent='space-between' columnGap={1}>
53
+ <text fg={context.theme.textMuted} wrapMode='none' flexShrink={0}>
54
+ {props.label}
55
+ </text>
56
+ <text fg={context.theme[props.tone ?? 'text']} wrapMode='none' flexShrink={1}>
57
+ <b>{value()}</b>
58
+ </text>
59
+ </box>);
60
+ }
61
+ export function SidebarTextRow(props) {
62
+ const context = frameContext();
63
+ return (<text fg={context.theme[props.tone ?? 'textMuted']} wrapMode={props.wrapMode}>
64
+ {props.text}
65
+ </text>);
66
+ }
67
+ function usageTone(used, appearance) {
68
+ if (used >= appearance.errorThreshold)
69
+ return 'error';
70
+ if (used >= appearance.warnThreshold)
71
+ return 'warning';
72
+ return 'success';
73
+ }
74
+ function barSegments(used, appearance, pace) {
75
+ const width = appearance.barWidth;
76
+ const cells = (pct) => Math.max(0, Math.min(Math.round((pct / 100) * width), width));
77
+ const usedCells = cells(used);
78
+ const tone = usageTone(used, appearance);
79
+ const plain = [
80
+ { text: appearance.barFilledChar.repeat(usedCells), tone },
81
+ { text: appearance.barEmptyChar.repeat(width - usedCells), tone },
82
+ ];
83
+ const overlay = pace?.overlay;
84
+ if (!overlay)
85
+ return plain.filter((segment) => segment.text.length > 0);
86
+ const paceCells = cells(overlay.percent);
87
+ const lo = Math.min(usedCells, paceCells);
88
+ const hi = Math.max(usedCells, paceCells);
89
+ if (lo === hi)
90
+ return plain.filter((segment) => segment.text.length > 0);
91
+ return [
92
+ { text: appearance.barFilledChar.repeat(lo), tone },
93
+ {
94
+ text: (overlay.kind === 'deficit' ? '\u2593' : '\u2592').repeat(hi - lo),
95
+ tone: overlay.kind === 'deficit' ? 'error' : 'success',
96
+ },
97
+ { text: appearance.barEmptyChar.repeat(width - hi), tone },
98
+ ].filter((segment) => segment.text.length > 0);
99
+ }
100
+ function QuotaRow(props) {
101
+ const context = frameContext();
102
+ const [columns, setColumns] = createSignal(0);
103
+ let row;
104
+ const label = () => props.part.name +
105
+ ' '.repeat(Math.max(0, props.labelWidth - displayWidth(props.part.name)));
106
+ const figure = () => ` ${props.part.kind === 'budget' && props.part.figure.startsWith(`${props.part.name} `) ? props.part.figure.slice(props.part.name.length + 1) : props.part.figure}`;
107
+ const used = () => 100 - (props.part.remainingPercent ?? 100);
108
+ const paceLine = () => {
109
+ const text = props.pace?.text;
110
+ if (!text || columns() <= 0)
111
+ return text;
112
+ return fitText(text, columns() - props.labelWidth);
113
+ };
114
+ return (<>
115
+ <box ref={(element) => {
116
+ row = element;
117
+ }} onSizeChange={() => setColumns(row?.width ?? 0)} width='100%' flexDirection='row' justifyContent='space-between'>
118
+ <box flexDirection='row' flexShrink={props.part.resetSinceReading ? 1 : 0}>
119
+ <Show when={props.labelWidth > 0}>
120
+ <text fg={context.theme.textMuted} wrapMode='none' flexShrink={0}>
121
+ {label()}
122
+ </text>
123
+ </Show>
124
+ <Show when={!props.part.resetSinceReading} fallback={<text fg={context.theme.textMuted} wrapMode='none'>
125
+ reset since last check
126
+ </text>}>
127
+ <For each={barSegments(used(), { ...context.appearance, barWidth: props.barCells }, props.pace)}>
128
+ {(segment) => (<text fg={context.theme[segment.tone]} wrapMode='none'>
129
+ {segment.text}
130
+ </text>)}
131
+ </For>
132
+ <text fg={context.theme[usageTone(used(), context.appearance)]} wrapMode='none'>
133
+ {figure()}
134
+ </text>
135
+ </Show>
136
+ </box>
137
+ <Show when={props.showReset && !props.part.resetSinceReading}>
138
+ <box width={props.resetWidth} flexShrink={0} flexDirection='row' justifyContent='flex-end'>
139
+ <Show when={props.part.resetIn}>
140
+ <text fg={context.theme.textMuted} wrapMode='none'>
141
+ {props.part.resetIn}
142
+ </text>
143
+ </Show>
144
+ </box>
145
+ </Show>
146
+ </box>
147
+ {/* A changed fitted line needs a fresh text node to draw at its new width. */}
148
+ <Show when={!props.part.resetSinceReading && paceLine()} keyed>
149
+ {(line) => (<box width='100%' flexDirection='row'>
150
+ <Show when={props.labelWidth > 0}>
151
+ <text fg={context.theme.textMuted}>
152
+ {''.padEnd(props.labelWidth)}
153
+ </text>
154
+ </Show>
155
+ <text fg={context.theme[props.pace?.tone ?? 'textMuted']} wrapMode='none'>
156
+ {line}
157
+ </text>
158
+ </box>)}
159
+ </Show>
160
+ </>);
161
+ }
162
+ function CollapsedAccountRow(props) {
163
+ const context = frameContext();
164
+ const [width, setWidth] = createSignal(0);
165
+ let row;
166
+ const hasQuota = () => quotaWindowParts(props.account.quota, { now: context.now }).windows.length >
167
+ 0;
168
+ const text = () => hasQuota()
169
+ ? formatQuota(props.account.quota, { now: context.now, form: 'narrow' })
170
+ : (props.account.emptyQuotaText?.collapsed ?? '\u2014');
171
+ // Reserve an ellipsis, a separator and the trailing indicator before keeping quota.
172
+ const showQuota = () => width() <= 0 || displayWidth(text()) + 4 <= width();
173
+ const label = () => {
174
+ if (width() <= 0)
175
+ return props.account.label;
176
+ return fitText(props.account.label, width() - (showQuota() ? displayWidth(text()) + 3 : 2));
177
+ };
178
+ const muted = () => props.account.collapsed?.muted ?? false;
179
+ const quotaTone = () => muted() ? 'textMuted' : (props.account.collapsed?.quotaTone ?? 'success');
180
+ return (<box ref={(element) => {
181
+ row = element;
182
+ }} onSizeChange={() => setWidth(row?.width ?? 0)} width='100%' flexDirection='row' justifyContent='space-between' columnGap={label() ? 1 : 0}>
183
+ <Show when={label()}>
184
+ <text fg={context.theme[muted() ? 'textMuted' : 'text']} wrapMode='none' flexShrink={1}>
185
+ {label()}
186
+ </text>
187
+ </Show>
188
+ <box flexDirection='row' flexShrink={0}>
189
+ <Show when={showQuota()}>
190
+ <Show when={hasQuota() && !muted()} fallback={<text fg={context.theme.textMuted}>{text()}</text>}>
191
+ <text fg={context.theme[quotaTone()]}>
192
+ <b>{text()}</b>
193
+ </text>
194
+ </Show>
195
+ </Show>
196
+ <text fg={context.theme[props.account.indicatorTone]}>
197
+ {showQuota() ? ' ' : ''}
198
+ {props.account.blocked ? '\u2298' : '\u25cf'}
199
+ </text>
200
+ </box>
201
+ </box>);
202
+ }
203
+ function AccountBlock(props) {
204
+ const context = frameContext();
205
+ const [columns, setColumns] = createSignal(0);
206
+ let block;
207
+ const rows = () => props.account.groups.flatMap((group) => group.rows);
208
+ const labelWidth = () => Math.max(0, ...rows().map(({ part }) => part.name ? Math.max(3, displayWidth(part.name) + 1) : 0));
209
+ const resetWidth = () => Math.max(0, ...rows().map(({ part }) => part.resetSinceReading ? 0 : displayWidth(part.resetIn ?? '')));
210
+ const figureWidth = createMemo(() => Math.max(10, ...rows()
211
+ .filter(({ part }) => !part.resetSinceReading)
212
+ .map(({ part }) => displayWidth(` ${part.kind === 'budget' && part.figure.startsWith(`${part.name} `) ? part.figure.slice(part.name.length + 1) : part.figure}`))));
213
+ const fit = (rowLabelWidth) => {
214
+ const desired = context.appearance.barWidth;
215
+ // Four cells still distinguish quarters of a window without sacrificing its reset.
216
+ const minimum = Math.min(4, desired);
217
+ if (columns() <= 0)
218
+ return { barCells: desired, showReset: resetWidth() > 0 };
219
+ const room = columns() - rowLabelWidth - figureWidth();
220
+ const withReset = room - resetWidth() - 1;
221
+ const showReset = resetWidth() > 0 && withReset >= minimum;
222
+ const available = showReset ? withReset : room;
223
+ return {
224
+ barCells: available >= minimum ? Math.min(desired, available) : 0,
225
+ showReset,
226
+ };
227
+ };
228
+ const label = () => {
229
+ const full = `${props.account.label}${props.account.titleSuffix ? ` · ${props.account.titleSuffix}` : ''}`;
230
+ return columns() <= 0
231
+ ? full
232
+ : fitText(full, columns() - displayWidth(props.account.status.text) - 1);
233
+ };
234
+ const age = () => quotaWindowParts(props.account.quota, { now: context.now }).age;
235
+ const hasRows = () => props.account.groups.some((group) => group.rows.length > 0);
236
+ return (<box ref={(element) => {
237
+ block = element;
238
+ }} onSizeChange={() => setColumns(block?.width ?? 0)} width='100%' flexDirection='column' marginTop={props.marginTop}>
239
+ <box width='100%' flexDirection='row' justifyContent='space-between' columnGap={1}>
240
+ <text fg={context.theme.text} wrapMode='none' flexShrink={1}>
241
+ <b>{label()}</b>
242
+ </text>
243
+ <text fg={context.theme[props.account.status.tone]} wrapMode='none' flexShrink={0}>
244
+ <b>{props.account.status.text}</b>
245
+ </text>
246
+ </box>
247
+ {context.beforeQuota?.(props.account)}
248
+ <Show when={hasRows()} fallback={<SidebarTextRow text={props.account.emptyQuotaText?.expanded ?? '\u2014'} wrapMode='none'/>}>
249
+ <For each={props.account.groups}>
250
+ {(group) => (<>
251
+ <Show when={group.title}>
252
+ <SidebarTextRow text={group.title ?? ''} tone='text' wrapMode='none'/>
253
+ </Show>
254
+ <For each={group.rows}>
255
+ {(row) => {
256
+ const rowLabelWidth = () => (row.part.name ? labelWidth() : 0);
257
+ const rowFit = createMemo(() => fit(rowLabelWidth()));
258
+ return (<QuotaRow part={row.part} pace={row.pace} labelWidth={rowLabelWidth()} barCells={rowFit().barCells} resetWidth={resetWidth()} showReset={rowFit().showReset}/>);
259
+ }}
260
+ </For>
261
+ </>)}
262
+ </For>
263
+ </Show>
264
+ <Show when={age()}>
265
+ {(text) => (<SidebarTextRow text={text()} wrapMode='none'/>)}
266
+ </Show>
267
+ {context.afterQuota?.(props.account)}
268
+ </box>);
269
+ }
270
+ /** Borderless, controlled presentation; host registration and provider policy stay in the plugin. */
271
+ export function SidebarFrame(props) {
272
+ const hasData = () => props.accounts.length > 0;
273
+ const headerLabel = () => !hasData()
274
+ ? props.header.badge
275
+ : `${props.collapsed ? '\u25b6' : '\u25bc'} ${props.header.badge}`;
276
+ // Missing semantic colors inherit normal text; an unset palette uses terminal defaults.
277
+ const context = mergeProps(props, {
278
+ get theme() {
279
+ const theme = props.theme;
280
+ return {
281
+ ...theme,
282
+ textMuted: theme?.textMuted ?? theme?.text,
283
+ accent: theme?.accent ?? theme?.text,
284
+ success: theme?.success ?? theme?.text,
285
+ warning: theme?.warning ?? theme?.text,
286
+ error: theme?.error ?? theme?.text,
287
+ };
288
+ },
289
+ });
290
+ // Inverting an incomplete badge palette can put light text on a light background.
291
+ const invertBadge = () => props.theme?.accent !== undefined && props.theme?.background !== undefined;
292
+ return (<FrameContext.Provider value={context}>
293
+ <box width='100%' flexDirection='column'>
294
+ {/* Blocked accounts retain their own indicators; the header always keeps its version. */}
295
+ {/* biome-ignore lint/a11y/noStaticElementInteractions: OpenTUI terminal widgets do not have DOM roles */}
296
+ <box width='100%' flexDirection='row' justifyContent='space-between' alignItems='center' onMouseDown={() => {
297
+ if (hasData())
298
+ props.onToggle();
299
+ }}>
300
+ <box paddingLeft={1} paddingRight={1} backgroundColor={invertBadge() ? props.theme?.accent : undefined}>
301
+ <text fg={invertBadge() ? props.theme?.background : context.theme.accent}>
302
+ <b>{headerLabel()}</b>
303
+ </text>
304
+ </box>
305
+ <Show when={props.header.version}>
306
+ <text fg={context.theme.textMuted}>{props.header.version}</text>
307
+ </Show>
308
+ </box>
309
+ <Show when={props.collapsed && hasData()}>
310
+ <For each={props.accounts}>
311
+ {(account) => <CollapsedAccountRow account={account}/>}
312
+ </For>
313
+ {props.collapsedSections?.()}
314
+ </Show>
315
+ <Show when={!props.collapsed || !hasData()}>
316
+ <Show when={props.showQuota && hasData()}>
317
+ <SidebarSection title='Quota'>
318
+ <For each={props.accounts}>
319
+ {(account, index) => (<AccountBlock account={account} marginTop={index() === 0 ? 0 : 1}/>)}
320
+ </For>
321
+ </SidebarSection>
322
+ </Show>
323
+ {props.sections?.()}
324
+ </Show>
325
+ </box>
326
+ </FrameContext.Provider>);
327
+ }
@@ -0,0 +1,56 @@
1
+ /** An eligible vault route, not a local pool row. */
2
+ export interface RoutingCandidate {
3
+ /** Vault account id, not the plugin's route id. */
4
+ accountId: string;
5
+ credentialId: string;
6
+ }
7
+ export interface AskRoutingInput<Candidate extends RoutingCandidate = RoutingCandidate> {
8
+ sessionId: string;
9
+ provider: string;
10
+ modelId: string;
11
+ /** Only routes already eligible under the plugin's vault and killswitch rules. */
12
+ candidates: readonly Candidate[];
13
+ /** Defaults to 500 ms, clamped to 1–2000 ms. */
14
+ deadlineMs?: number;
15
+ }
16
+ export interface RoutingHold {
17
+ /** Uncapped advice from routing. The plugin must apply its own hold cap. */
18
+ retry_after_ms: number;
19
+ }
20
+ export interface RoutingSelection<Candidate extends RoutingCandidate = RoutingCandidate> {
21
+ /** The original eligible candidate, including any plugin-specific metadata. */
22
+ candidate: Candidate;
23
+ hold?: RoutingHold;
24
+ }
25
+ interface RoutingReportIdentity {
26
+ sessionId: string;
27
+ accountId: string;
28
+ credentialId?: string;
29
+ }
30
+ export type ReportRoutingInput = RoutingReportIdentity & ({
31
+ outcome: 'served';
32
+ /**
33
+ * Pass only rate-limit headers, never the whole response headers.
34
+ * Values are forwarded unchanged; do not include tokens, emails or labels.
35
+ */
36
+ headers: Readonly<Record<string, string>>;
37
+ } | {
38
+ outcome: 'exhausted';
39
+ /** A quota window such as `5h`, `7d` or a scoped window id. */
40
+ window: string;
41
+ /** Optional reset time in epoch milliseconds. */
42
+ resetsAt?: number;
43
+ });
44
+ /**
45
+ * Ask routing for an eligible vault route. Any failure or unfamiliar answer
46
+ * yields undefined so the plugin can keep its own choice. This does not admit
47
+ * routes: callers must exclude vault refusals and killswitch-blocked accounts.
48
+ */
49
+ export declare function askRouting<Candidate extends RoutingCandidate>(input: AskRoutingInput<Candidate>): Promise<RoutingSelection<Candidate> | undefined>;
50
+ /**
51
+ * Report a vault request without waiting for routing. Only contract fields are
52
+ * sent, and all accessor failures are ignored. Headers must already be limited
53
+ * to rate-limit headers by the caller; values are not filtered or redacted here.
54
+ */
55
+ export declare function reportRouting(input: ReportRoutingInput): void;
56
+ export {};