@cortexkit/opencode-antigravity-auth 3.0.6 → 3.0.8

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.
Files changed (211) hide show
  1. package/dist/cli.js +1621 -183
  2. package/dist/cli.js.map +4 -4
  3. package/dist/cli.meta.json +228 -62
  4. package/dist/index.js +2728 -883
  5. package/dist/index.js.map +4 -4
  6. package/dist/index.meta.json +291 -104
  7. package/dist/server.js +2255 -390
  8. package/dist/server.js.map +4 -4
  9. package/dist/server.meta.json +1 -1
  10. package/dist/src/common-auth-embedded/claustrum/availability.d.ts +89 -0
  11. package/dist/src/common-auth-embedded/claustrum/availability.js +106 -0
  12. package/dist/src/common-auth-embedded/claustrum/consumer.d.ts +41 -1
  13. package/dist/src/common-auth-embedded/claustrum/consumer.js +152 -6
  14. package/dist/src/common-auth-embedded/claustrum/custody.d.ts +135 -14
  15. package/dist/src/common-auth-embedded/claustrum/custody.js +311 -16
  16. package/dist/src/common-auth-embedded/claustrum/errors.d.ts +1 -0
  17. package/dist/src/common-auth-embedded/claustrum/index.d.ts +5 -3
  18. package/dist/src/common-auth-embedded/claustrum/index.js +4 -1
  19. package/dist/src/common-auth-embedded/claustrum/insula.d.ts +48 -0
  20. package/dist/src/common-auth-embedded/claustrum/insula.js +286 -21
  21. package/dist/src/common-auth-embedded/claustrum/watch.d.ts +141 -0
  22. package/dist/src/common-auth-embedded/claustrum/watch.js +254 -0
  23. package/dist/src/common-auth-embedded/fs/private-files.js +10 -2
  24. package/dist/src/common-auth-embedded/fs/refresh-file-lock.d.ts +8 -2
  25. package/dist/src/common-auth-embedded/fs/refresh-file-lock.js +6 -1
  26. package/dist/src/common-auth-embedded/pi-slot/lock.js +7 -3
  27. package/dist/src/common-auth-embedded/quota/format.d.ts +17 -3
  28. package/dist/src/common-auth-embedded/quota/format.js +203 -18
  29. package/dist/src/common-auth-embedded/quota/index.d.ts +2 -2
  30. package/dist/src/common-auth-embedded/quota/index.js +1 -1
  31. package/dist/src/common-auth-embedded/quota/projection.d.ts +16 -0
  32. package/dist/src/common-auth-embedded/setup/command-error.d.ts +32 -0
  33. package/dist/src/common-auth-embedded/setup/command-error.js +79 -0
  34. package/dist/src/common-auth-embedded/setup/command-runner.js +118 -24
  35. package/dist/src/common-auth-embedded/setup/command.js +75 -19
  36. package/dist/src/common-auth-embedded/setup/enroll.js +17 -5
  37. package/dist/src/common-auth-embedded/setup/index.d.ts +2 -1
  38. package/dist/src/common-auth-embedded/setup/index.js +1 -0
  39. package/dist/src/common-auth-embedded/setup/register.js +8 -2
  40. package/dist/src/common-auth-embedded/setup/types.d.ts +14 -0
  41. package/dist/src/common-auth-embedded/source-output.json +142 -94
  42. package/dist/src/common-auth-embedded/store/pool.d.ts +1 -1
  43. package/dist/src/common-auth-embedded/store/pool.js +0 -1
  44. package/dist/src/common-auth-embedded/store/refresh-lock.d.ts +0 -1
  45. package/dist/src/common-auth-embedded/store/refresh-lock.js +0 -1
  46. package/dist/src/ga/server/index.d.ts +2 -0
  47. package/dist/src/ga/server/index.d.ts.map +1 -1
  48. package/dist/src/ga/server/index.js +18 -3
  49. package/dist/src/ga/server/index.js.map +1 -1
  50. package/dist/src/ga/tui/host-ga.d.ts.map +1 -1
  51. package/dist/src/ga/tui/host-ga.js +37 -3
  52. package/dist/src/ga/tui/host-ga.js.map +1 -1
  53. package/dist/src/plugin/auth-loader.d.ts +2 -1
  54. package/dist/src/plugin/auth-loader.d.ts.map +1 -1
  55. package/dist/src/plugin/auth-loader.js +5 -4
  56. package/dist/src/plugin/auth-loader.js.map +1 -1
  57. package/dist/src/plugin/config/schema.d.ts.map +1 -1
  58. package/dist/src/plugin/config/schema.js +2 -1
  59. package/dist/src/plugin/config/schema.js.map +1 -1
  60. package/dist/src/plugin/fetch-interceptor.d.ts +2 -1
  61. package/dist/src/plugin/fetch-interceptor.d.ts.map +1 -1
  62. package/dist/src/plugin/fetch-interceptor.js +8 -6
  63. package/dist/src/plugin/fetch-interceptor.js.map +1 -1
  64. package/dist/src/plugin/ga-location-services.d.ts.map +1 -1
  65. package/dist/src/plugin/ga-location-services.js +7 -3
  66. package/dist/src/plugin/ga-location-services.js.map +1 -1
  67. package/dist/src/plugin/gemini-dump.d.ts.map +1 -1
  68. package/dist/src/plugin/gemini-dump.js +2 -5
  69. package/dist/src/plugin/gemini-dump.js.map +1 -1
  70. package/dist/src/plugin/index.d.ts.map +1 -1
  71. package/dist/src/plugin/index.js +3 -3
  72. package/dist/src/plugin/index.js.map +1 -1
  73. package/dist/src/plugin/logging-utils.d.ts.map +1 -1
  74. package/dist/src/plugin/logging-utils.js +2 -5
  75. package/dist/src/plugin/logging-utils.js.map +1 -1
  76. package/dist/src/plugin/request.d.ts +1 -2
  77. package/dist/src/plugin/request.d.ts.map +1 -1
  78. package/dist/src/plugin/request.js +8 -12
  79. package/dist/src/plugin/request.js.map +1 -1
  80. package/dist/src/plugin/shared/after-handoff.d.ts +14 -0
  81. package/dist/src/plugin/shared/after-handoff.d.ts.map +1 -0
  82. package/dist/src/plugin/shared/after-handoff.js +89 -0
  83. package/dist/src/plugin/shared/after-handoff.js.map +1 -0
  84. package/dist/src/plugin/shared/request-services.d.ts +16 -3
  85. package/dist/src/plugin/shared/request-services.d.ts.map +1 -1
  86. package/dist/src/plugin/shared/request-services.js +193 -90
  87. package/dist/src/plugin/shared/request-services.js.map +1 -1
  88. package/dist/src/plugin/shared/vault-request-credentials.d.ts +13 -4
  89. package/dist/src/plugin/shared/vault-request-credentials.d.ts.map +1 -1
  90. package/dist/src/plugin/shared/vault-request-credentials.js +17 -1
  91. package/dist/src/plugin/shared/vault-request-credentials.js.map +1 -1
  92. package/dist/src/plugin/vault-custody.d.ts +16 -1
  93. package/dist/src/plugin/vault-custody.d.ts.map +1 -1
  94. package/dist/src/plugin/vault-custody.js +60 -10
  95. package/dist/src/plugin/vault-custody.js.map +1 -1
  96. package/dist/src/sidebar-projection.d.ts +4 -0
  97. package/dist/src/sidebar-projection.d.ts.map +1 -1
  98. package/dist/src/sidebar-projection.js +6 -2
  99. package/dist/src/sidebar-projection.js.map +1 -1
  100. package/dist/src/tui/quota-layout.d.ts +94 -0
  101. package/dist/src/tui/quota-layout.d.ts.map +1 -0
  102. package/dist/src/tui/quota-layout.js +139 -0
  103. package/dist/src/tui/quota-layout.js.map +1 -0
  104. package/dist/src/tui/route-layout.d.ts +8 -0
  105. package/dist/src/tui/route-layout.d.ts.map +1 -0
  106. package/dist/src/tui/route-layout.js +36 -0
  107. package/dist/src/tui/route-layout.js.map +1 -0
  108. package/dist/src/tui.d.ts.map +1 -1
  109. package/dist/src/tui.js +105 -191
  110. package/dist/src/tui.js.map +1 -1
  111. package/dist/tui-build-map.json +60 -31
  112. package/dist/tui-ga-build-map.json +46 -17
  113. package/dist/types/src/common-auth-embedded/claustrum/availability.d.ts +89 -0
  114. package/dist/types/src/common-auth-embedded/claustrum/consumer.d.ts +41 -1
  115. package/dist/types/src/common-auth-embedded/claustrum/custody.d.ts +135 -14
  116. package/dist/types/src/common-auth-embedded/claustrum/errors.d.ts +1 -0
  117. package/dist/types/src/common-auth-embedded/claustrum/index.d.ts +5 -3
  118. package/dist/types/src/common-auth-embedded/claustrum/insula.d.ts +48 -0
  119. package/dist/types/src/common-auth-embedded/claustrum/watch.d.ts +141 -0
  120. package/dist/types/src/common-auth-embedded/fs/refresh-file-lock.d.ts +8 -2
  121. package/dist/types/src/common-auth-embedded/quota/format.d.ts +17 -3
  122. package/dist/types/src/common-auth-embedded/quota/index.d.ts +2 -2
  123. package/dist/types/src/common-auth-embedded/quota/projection.d.ts +16 -0
  124. package/dist/types/src/common-auth-embedded/setup/command-error.d.ts +32 -0
  125. package/dist/types/src/common-auth-embedded/setup/index.d.ts +2 -1
  126. package/dist/types/src/common-auth-embedded/setup/types.d.ts +14 -0
  127. package/dist/types/src/common-auth-embedded/store/pool.d.ts +1 -1
  128. package/dist/types/src/common-auth-embedded/store/refresh-lock.d.ts +0 -1
  129. package/dist/types/src/ga/server/index.d.ts +2 -0
  130. package/dist/types/src/ga/server/index.d.ts.map +1 -1
  131. package/dist/types/src/plugin/auth-loader.d.ts +2 -1
  132. package/dist/types/src/plugin/auth-loader.d.ts.map +1 -1
  133. package/dist/types/src/plugin/config/schema.d.ts.map +1 -1
  134. package/dist/types/src/plugin/fetch-interceptor.d.ts +2 -1
  135. package/dist/types/src/plugin/fetch-interceptor.d.ts.map +1 -1
  136. package/dist/types/src/plugin/ga-location-services.d.ts.map +1 -1
  137. package/dist/types/src/plugin/gemini-dump.d.ts.map +1 -1
  138. package/dist/types/src/plugin/index.d.ts.map +1 -1
  139. package/dist/types/src/plugin/logging-utils.d.ts.map +1 -1
  140. package/dist/types/src/plugin/request.d.ts +1 -2
  141. package/dist/types/src/plugin/request.d.ts.map +1 -1
  142. package/dist/types/src/plugin/shared/after-handoff.d.ts +14 -0
  143. package/dist/types/src/plugin/shared/after-handoff.d.ts.map +1 -0
  144. package/dist/types/src/plugin/shared/request-services.d.ts +16 -3
  145. package/dist/types/src/plugin/shared/request-services.d.ts.map +1 -1
  146. package/dist/types/src/plugin/shared/vault-request-credentials.d.ts +13 -4
  147. package/dist/types/src/plugin/shared/vault-request-credentials.d.ts.map +1 -1
  148. package/dist/types/src/plugin/vault-custody.d.ts +16 -1
  149. package/dist/types/src/plugin/vault-custody.d.ts.map +1 -1
  150. package/package.json +4 -4
  151. package/src/common-auth-embedded/claustrum/availability.d.ts +89 -0
  152. package/src/common-auth-embedded/claustrum/availability.js +106 -0
  153. package/src/common-auth-embedded/claustrum/consumer.d.ts +41 -1
  154. package/src/common-auth-embedded/claustrum/consumer.js +152 -6
  155. package/src/common-auth-embedded/claustrum/custody.d.ts +135 -14
  156. package/src/common-auth-embedded/claustrum/custody.js +311 -16
  157. package/src/common-auth-embedded/claustrum/errors.d.ts +1 -0
  158. package/src/common-auth-embedded/claustrum/index.d.ts +5 -3
  159. package/src/common-auth-embedded/claustrum/index.js +4 -1
  160. package/src/common-auth-embedded/claustrum/insula.d.ts +48 -0
  161. package/src/common-auth-embedded/claustrum/insula.js +286 -21
  162. package/src/common-auth-embedded/claustrum/watch.d.ts +141 -0
  163. package/src/common-auth-embedded/claustrum/watch.js +254 -0
  164. package/src/common-auth-embedded/fs/private-files.js +10 -2
  165. package/src/common-auth-embedded/fs/refresh-file-lock.d.ts +8 -2
  166. package/src/common-auth-embedded/fs/refresh-file-lock.js +6 -1
  167. package/src/common-auth-embedded/pi-slot/lock.js +7 -3
  168. package/src/common-auth-embedded/quota/format.d.ts +17 -3
  169. package/src/common-auth-embedded/quota/format.js +203 -18
  170. package/src/common-auth-embedded/quota/index.d.ts +2 -2
  171. package/src/common-auth-embedded/quota/index.js +1 -1
  172. package/src/common-auth-embedded/quota/projection.d.ts +16 -0
  173. package/src/common-auth-embedded/setup/command-error.d.ts +32 -0
  174. package/src/common-auth-embedded/setup/command-error.js +79 -0
  175. package/src/common-auth-embedded/setup/command-runner.js +118 -24
  176. package/src/common-auth-embedded/setup/command.js +75 -19
  177. package/src/common-auth-embedded/setup/enroll.js +17 -5
  178. package/src/common-auth-embedded/setup/index.d.ts +2 -1
  179. package/src/common-auth-embedded/setup/index.js +1 -0
  180. package/src/common-auth-embedded/setup/register.js +8 -2
  181. package/src/common-auth-embedded/setup/types.d.ts +14 -0
  182. package/src/common-auth-embedded/source-output.json +142 -94
  183. package/src/common-auth-embedded/store/pool.d.ts +1 -1
  184. package/src/common-auth-embedded/store/pool.js +0 -1
  185. package/src/common-auth-embedded/store/refresh-lock.d.ts +0 -1
  186. package/src/common-auth-embedded/store/refresh-lock.js +0 -1
  187. package/src/tui-compiled/common-auth-embedded/fs/private-files.js +10 -2
  188. package/src/tui-compiled/common-auth-embedded/quota/format.js +203 -18
  189. package/src/tui-compiled/common-auth-embedded/quota/index.js +1 -1
  190. package/src/tui-compiled/tui/quota-layout.js +378 -0
  191. package/src/tui-compiled/tui/route-layout.js +30 -0
  192. package/src/tui-compiled/tui.js +245 -501
  193. package/src/tui-ga-compiled/host-ga.js +82 -52
  194. package/src/tui-ga-compiled/shared/6ca47cd4ec33fe72-route-layout.js +30 -0
  195. package/src/tui-ga-compiled/shared/8ae1927e5910ea81-sidebar-projection.js +2 -2
  196. package/src/tui-ga-compiled/shared/aef2402f8fc342f0-format.js +203 -18
  197. package/src/tui-ga-compiled/shared/bf17cbee28e58197-index.js +1 -1
  198. package/src/tui-ga-compiled/shared/dd4c9e1a907f8ef0-quota-layout.js +378 -0
  199. package/src/tui-ga-raw/host-ga.tsx +71 -30
  200. package/src/tui-ga-raw/shared/6ca47cd4ec33fe72-route-layout.js +30 -0
  201. package/src/tui-ga-raw/shared/8ae1927e5910ea81-sidebar-projection.js +2 -2
  202. package/src/tui-ga-raw/shared/aef2402f8fc342f0-format.js +203 -18
  203. package/src/tui-ga-raw/shared/bf17cbee28e58197-index.js +1 -1
  204. package/src/tui-ga-raw/shared/dd4c9e1a907f8ef0-quota-layout.tsx +391 -0
  205. package/src/tui-raw/common-auth-embedded/fs/private-files.js +10 -2
  206. package/src/tui-raw/common-auth-embedded/quota/format.js +203 -18
  207. package/src/tui-raw/common-auth-embedded/quota/index.js +1 -1
  208. package/src/tui-raw/tui/quota-layout.tsx +391 -0
  209. package/src/tui-raw/tui/route-layout.js +30 -0
  210. package/src/tui-raw/tui.tsx +171 -411
  211. package/src/tui.tsx +171 -411
@@ -1,9 +1,14 @@
1
1
  import { type ClaustrumClient, type ClaustrumReporterSource, type EnrollmentTokenFile } from '@cortexkit/claustrum-client';
2
2
  import { type ClaustrumLogger } from './errors.js';
3
3
  import type { InsulaUsageTransport } from './insula.js';
4
+ import { type ScopedWatchSource, type WatchMode } from './watch.js';
5
+ /**
6
+ * `watchScoped` is present from claustrum-client 0.12.0. Hosts detect it at
7
+ * run time and keep polling without it.
8
+ */
4
9
  export type ClaustrumScopedClient = Pick<ClaustrumClient, 'listScoped' | 'getScoped' | 'reportAuthFailureScoped' | 'close'> & {
5
10
  insula?: InsulaUsageTransport;
6
- };
11
+ } & ScopedWatchSource;
7
12
  /** The two credential types a plugin's family can hold; routing differs by type. */
8
13
  export type VaultCredentialType = 'oauth' | 'api_key';
9
14
  /**
@@ -44,6 +49,30 @@ export interface SkippedVaultRecord {
44
49
  readonly credentialId?: string;
45
50
  readonly reason: SkippedVaultReason;
46
51
  }
52
+ /**
53
+ * One grant this consumer's enrollment holds, as the vault's list reply names
54
+ * it: for example `{ selectorKind: 'category', selector: 'openai-native',
55
+ * operation: 'read' }`. `selectorKind` is `exact` (the selector is a credential
56
+ * id) or `category` (a bare category name); both open strings.
57
+ */
58
+ export interface VaultGrantTuple {
59
+ readonly selectorKind: string;
60
+ readonly selector: string;
61
+ readonly operation: string;
62
+ }
63
+ /**
64
+ * What this consumer is granted, independent of what those grants currently
65
+ * reach. It is what tells two empty listings apart: no rows with `grants === 0`
66
+ * means no grant at all (the fix is `ck auth grant`), while no rows with
67
+ * `grants > 0` means a grant that reaches no credential, usually logins that
68
+ * lack the category (`ck auth reclassify --from-registry`); `tuples` names the
69
+ * selector that matched nothing. Never written to the roster file.
70
+ */
71
+ export interface VaultGrantReach {
72
+ /** How many grants the consumer holds, deposit grants excluded. */
73
+ readonly grants: number;
74
+ readonly tuples: readonly VaultGrantTuple[];
75
+ }
47
76
  export interface VaultInventory {
48
77
  /**
49
78
  * The vault's change cursor: a digest over exactly what this consumer can see
@@ -53,6 +82,11 @@ export interface VaultInventory {
53
82
  readonly view: string;
54
83
  readonly credentials: readonly VaultCredential[];
55
84
  readonly skipped: readonly SkippedVaultRecord[];
85
+ /**
86
+ * The consumer's grants, as the vault's list reply named them. Undefined means unknown
87
+ * (the vault or client predates the fields), never zero grants.
88
+ */
89
+ readonly grantReach?: VaultGrantReach;
56
90
  }
57
91
  export interface ClaustrumScopedIdentity {
58
92
  readonly credentialId: string;
@@ -103,6 +137,57 @@ export interface ClaustrumScopedAttempt {
103
137
  readonly accessToken: string;
104
138
  readonly recordVersion: number;
105
139
  readonly expiresAtMs: number | null;
140
+ /**
141
+ * True when this receipt was not freshly served but is the last token kept
142
+ * from an earlier read, used because the vault could not be reached. A 401
143
+ * with such a receipt must not be retried and is not reported to the vault,
144
+ * which is unreachable.
145
+ */
146
+ readonly fromKeptReceipt?: true;
147
+ }
148
+ export interface KeptReceiptState {
149
+ readonly active: boolean;
150
+ readonly since: number | null;
151
+ }
152
+ export interface ClaustrumRosterWatchOptions {
153
+ /**
154
+ * Run the host's own discovery (`custody.discover()`, then its roster
155
+ * commit). Called with the newest notice's view when that view differs from
156
+ * the last discovered one, when a notice shows a sequence gap or a new
157
+ * epoch, and on the first notice of a watch re-opened after a close (the
158
+ * time between two watches was not observed). One call runs at a time;
159
+ * notices that arrive meanwhile earn at most one more call, which runs only
160
+ * if the view still differs. A rejection goes to `onError`.
161
+ */
162
+ onView: (view: string) => unknown;
163
+ /**
164
+ * The view of the roster the host last committed. Defaults to the view of
165
+ * the last successful `custody.discover()` (outage probes excluded). Pass it
166
+ * when the host can commit a roster it did not list itself (a peer process
167
+ * held the discovery lease) or can fail after listing.
168
+ */
169
+ view?: () => string | undefined;
170
+ /**
171
+ * Called whenever the mode changes. The watch starts in `polling`. Keep the
172
+ * host's own list timer at its usual pace unless the mode is `watching`.
173
+ */
174
+ onMode?: (mode: WatchMode) => void;
175
+ /**
176
+ * The vault refused the watch, and its confirming `list_scoped` read it with
177
+ * this error (a revoked enrollment answers `not_found`). Custody has already
178
+ * applied it as it applies a refused discovery (`listFailed`: every kept
179
+ * receipt is dropped); handle it as the host handles that refusal.
180
+ */
181
+ onRefused?: (error: unknown) => void;
182
+ /** A failed `onView`, or a watch that could not be opened. */
183
+ onError?: (error: unknown) => void;
184
+ }
185
+ /** A vault watch held by a custody; see `ClaustrumScopedCustody.watchRoster`. */
186
+ export interface ClaustrumRosterWatch {
187
+ /** How the host currently learns about changes. */
188
+ readonly mode: WatchMode;
189
+ /** Stop the watch and its timers. Safe to call more than once. */
190
+ close(): void;
106
191
  }
107
192
  /** Reads the provider identity a served token executes under, when the plugin can tell. */
108
193
  export type IdentityParser = (accessToken: string) => string | undefined;
@@ -122,13 +207,15 @@ export declare function decideScopedRetryAfter401(site: string, served: Claustru
122
207
  * so it cannot expire while a long request is still using it.
123
208
  */
124
209
  export declare const SERVING_MARGIN_MS = 300000;
210
+ /** A kept receipt needs a minute of headroom, not the vault's refresh demand. */
211
+ export declare const KEPT_RECEIPT_MARGIN_MS = 60000;
125
212
  /**
126
213
  * Reads this consumer's vault credentials (list, fetch, 401 report), with the
127
- * enrollment token as authorization. Used by every host of a plugin. There is
128
- * deliberately no credential cache and no single-flight of credential reads:
129
- * each physical send is authorized by the vault, so a revoked enrollment or a
130
- * changed record takes effect on the next send. The enrollment token is
131
- * re-read per operation so an operator's reissue on disk is picked up.
214
+ * enrollment token as authorization. Used by every host of a plugin. Every
215
+ * physical send asks the vault first while reachable. Only an unreachable vault permits
216
+ * reuse of the last validated receipt, in memory and bounded by its expiry.
217
+ * The enrollment token is re-read per operation so revocation and disconnect
218
+ * still take effect without a process restart.
132
219
  */
133
220
  export declare class ClaustrumScopedCustody {
134
221
  #private;
@@ -148,7 +235,13 @@ export declare class ClaustrumScopedCustody {
148
235
  requireAssertion?: boolean;
149
236
  now?: () => number;
150
237
  logger?: ClaustrumLogger;
238
+ setTimeoutImpl?: typeof setTimeout;
239
+ clearTimeoutImpl?: typeof clearTimeout;
151
240
  });
241
+ /** A watch losing its transport is the same outage as an unreachable read. */
242
+ transportLost(error?: unknown): void;
243
+ /** Any vault answer ends transport fallback, even when it refuses access. */
244
+ reachable(): void;
152
245
  /**
153
246
  * List this consumer's credentials. A record that cannot be used is skipped
154
247
  * and warned about rather than failing the whole list, so one bad record
@@ -157,15 +250,23 @@ export declare class ClaustrumScopedCustody {
157
250
  */
158
251
  discover(signal?: AbortSignal): Promise<VaultInventory>;
159
252
  /**
160
- * Fetch the credential for one physical send and wrap it in a fresh receipt.
161
- * The vault's served identity (or, without one, the plugin's parse of the
162
- * token) must equal the roster's when both are present. Without
163
- * `requireAssertion`, absence on either side proves nothing and does not
164
- * refuse; the receipt records what the vault asserted separately from what
165
- * the roster expected. With it, a reply that does not itself name the
166
- * credential id and the expected account is refused.
253
+ * Apply a failed account listing: any answer from the vault (a refusal such
254
+ * as a revoked enrollment's `not_found`) drops every kept receipt, while an
255
+ * unreachable vault keeps them. A vault watch that ends with the same
256
+ * refusal calls this too, so both paths treat it alike.
167
257
  */
168
- authorize(identity: ClaustrumScopedIdentity, signal?: AbortSignal): Promise<ClaustrumScopedAttempt>;
258
+ listFailed(error: unknown): void;
259
+ /** Discard bearer material when a route is removed, declined or rebound. */
260
+ forget(credentialId: string): void;
261
+ /** Apply an already-held roster; this never fetches credentials or writes it. */
262
+ retain(identities: readonly (ClaustrumScopedIdentity & {
263
+ enabled: boolean;
264
+ state: string;
265
+ })[]): void;
266
+ /** A frozen, non-secret summary for a plugin's status display. */
267
+ keptReceiptState(): KeptReceiptState;
268
+ /** Ask the vault while reachable; retain one validated receipt in memory only. */
269
+ authorize(identity: ClaustrumScopedIdentity, signal?: AbortSignal, routeId?: string): Promise<ClaustrumScopedAttempt>;
169
270
  /**
170
271
  * Report that a send this consumer actually made was rejected. Only a 401
171
272
  * is reported (the vault refuses 429, 402 and 5xx reports), addressed by
@@ -174,5 +275,25 @@ export declare class ClaustrumScopedCustody {
174
275
  * custody did not issue is refused rather than reported.
175
276
  */
176
277
  reportFailure(attempt: ClaustrumScopedAttempt, status: number, reporterSource: ClaustrumReporterSource): Promise<void>;
278
+ /**
279
+ * Watch this consumer's visible vault accounts instead of listing them on a
280
+ * short timer. Opens one `watchScoped` on this custody's client and calls
281
+ * `onView` when the host must run its discovery (see
282
+ * `ClaustrumRosterWatchOptions`). A claustrum-client without `watchScoped`
283
+ * (before 0.12.0) or a vault that answers `unknown_method` reports
284
+ * `fallback` and opens nothing. A watch that closes before any notice was
285
+ * never accepted: the client reads once to learn why, and the watch reports
286
+ * `fallback` and tries one new watch after `WATCH_RETRY_MS`, never in a
287
+ * loop. A watch that closes after notices is re-opened after
288
+ * `RESUBSCRIBE_BACKOFF_MS`, doubling per close in a row. A lost transport
289
+ * starts this custody's outage, exactly as an unreachable call does, and
290
+ * the first notice of a watch ends it. Timers are unreferenced; `close()`
291
+ * on the returned watch or on this custody stops it.
292
+ *
293
+ * The watch keeps no history, so the host still lists on a slow timer while
294
+ * the mode is `watching`: every `SAFETY_POLL_MS` (five minutes). In any
295
+ * other mode the host keeps its usual list timer.
296
+ */
297
+ watchRoster(options: ClaustrumRosterWatchOptions): ClaustrumRosterWatch;
177
298
  close(): void;
178
299
  }
@@ -11,6 +11,7 @@ export declare class ClaustrumConsumerError extends Error {
11
11
  }
12
12
  /** The structural logger every class here accepts; `/logger`'s `createLogger` satisfies it. */
13
13
  export interface ClaustrumLogger {
14
+ info?(message: string, data?: unknown): void;
14
15
  warn(message: string, data?: unknown): void;
15
16
  debug(message: string, data?: unknown): void;
16
17
  }
@@ -1,14 +1,16 @@
1
1
  import { type ClaustrumClientOptions } from '@cortexkit/claustrum-client';
2
2
  import type { ClaustrumScopedClient } from './custody.js';
3
3
  export { ClaustrumCredentialError, type ClaustrumReporterSource, type EnrollmentTokenFile, } from '@cortexkit/claustrum-client';
4
- export { ClaustrumConsumer, type ClaustrumConsumerOptions, type SendOptions, } from './consumer.js';
5
- export { type AccountIdentitySource, type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, ClaustrumScopedCustody, type ClaustrumScopedIdentity, decideScopedRetryAfter401, type IdentityParser, isScopedCredentialRotation, type ScopedRetryReason, SERVING_MARGIN_MS, type SkippedVaultReason, type SkippedVaultRecord, type VaultCredential, type VaultCredentialType, type VaultInventory, } from './custody.js';
4
+ export { ClaustrumUnreachableError, classifyVaultFailure, VAULT_FAILURE_CLASSES, type VaultFailureClass, } from './availability.js';
5
+ export { ClaustrumConsumer, type ClaustrumConsumerOptions, type ClaustrumWatchState, type SendOptions, } from './consumer.js';
6
+ export { type AccountIdentitySource, type ClaustrumFamily, type ClaustrumRosterWatch, type ClaustrumRosterWatchOptions, type ClaustrumScopedAttempt, type ClaustrumScopedClient, ClaustrumScopedCustody, type ClaustrumScopedIdentity, decideScopedRetryAfter401, type IdentityParser, isScopedCredentialRotation, KEPT_RECEIPT_MARGIN_MS, type KeptReceiptState, type ScopedRetryReason, SERVING_MARGIN_MS, type SkippedVaultReason, type SkippedVaultRecord, type VaultCredential, type VaultCredentialType, type VaultGrantReach, type VaultGrantTuple, type VaultInventory, } from './custody.js';
6
7
  export { type ClaustrumEnrollmentClient, type ClaustrumEnrollmentConnection, type ClaustrumEnrollmentDisconnectResult, ClaustrumEnrollmentManager, type ClaustrumEnrollmentPaths, type ClaustrumEnrollmentResetResult, type ClaustrumEnrollmentStatus, classifyEnrollmentError, connectClaustrumEnrollmentClient, disconnectClaustrumEnrollment, type EnrollmentDisposition, enrollmentAuthority, enrollmentName, getClaustrumEnrollmentPaths, hostEnrollmentPaths, RETRYABLE_ENROLLMENT_CODES, readClaustrumEnrollmentStatus, readClaustrumEnrollmentToken, resetClaustrumEnrollmentState, TERMINAL_ENROLLMENT_CODES, } from './enrollment.js';
7
8
  export { ClaustrumConsumerError, type ClaustrumConsumerFailureKind, type ClaustrumLogger, } from './errors.js';
8
9
  export { assertHostSlotMatchesMode, assertNotCustodyPlaceholder, CUSTODY_PLACEHOLDER_PREFIX, classifyHostSlot, custodyPlaceholder, custodyPlaceholderKey, type HostSlotContent, isCustodyPlaceholder, isCustodyPlaceholderValue, } from './host-slot.js';
9
- export type { InsulaQuotaContext, InsulaQuotaOptions, InsulaUsageEntry, InsulaUsageTransport, InsulaUsageWindow, } from './insula.js';
10
+ export { acquireInsulaQuotaSource, type InsulaQuotaContext, type InsulaQuotaOptions, type InsulaQuotaSource, type InsulaUsageEntry, type InsulaUsageTransport, type InsulaUsageWatch, type InsulaUsageWindow, type InsulaWatchOptions, } from './insula.js';
10
11
  export { acceptAccount, type DeclinedAccount, declineAccount, isDeclined, } from './interlock.js';
11
12
  export { type AccountMapper, acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, type MutateVaultRosterOptions, mutateVaultRoster, type ProjectionOptions, projectVaultRoster, type QuotaReceipt, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, resolveVaultPrimary, type VaultPrimary, type VaultPrimaryBinding, type VaultPrimaryUnavailableReason, type VaultRosterFile, type VaultRosterLockContext, type VaultRosterRow, vaultRoutingRows, } from './roster.js';
13
+ export { type ChangeNotice, ChangeNoticeReader, RESUBSCRIBE_BACKOFF_MS, SAFETY_POLL_MS, ScopedRosterWatch, type ScopedRosterWatchOptions, type ScopedWatchEnd, type ScopedWatchHandle, type ScopedWatchNoticeShape, type ScopedWatchSource, WATCH_RETRY_MS, type WatchMode, } from './watch.js';
12
14
  /**
13
15
  * Connect the client that lists and fetches this consumer's vault credentials
14
16
  * on the request path. `connectionFile` is required: this library
@@ -1,4 +1,5 @@
1
1
  import type { ClaustrumClientOptions } from '@cortexkit/claustrum-client';
2
+ import { type WatchMode } from './watch.js';
2
3
  /** Insula's window fields are open: plugins choose which limits they understand. */
3
4
  export interface InsulaUsageWindow {
4
5
  usedPercent: number;
@@ -43,21 +44,68 @@ export interface InsulaQuotaOptions<Q> {
43
44
  */
44
45
  normalize: (entry: InsulaUsageEntry, context: InsulaQuotaContext) => Q | undefined;
45
46
  }
47
+ /**
48
+ * A held-open `usage.watch` stream. `closed` resolves when insula ends the
49
+ * stream (STREAM_END at shutdown, or a reply that ends it) or after `stop()`,
50
+ * and rejects with insula's refusal (an error with a `code`, such as
51
+ * `unknown_method` from an insula that predates the method, or
52
+ * `usage_watch_limit` when 64 watches are already open) or with the
53
+ * transport failure.
54
+ */
55
+ export interface InsulaUsageWatch {
56
+ stop(): void;
57
+ readonly closed: Promise<void>;
58
+ }
46
59
  /** Optional transport for custom scoped clients; getUsage must not retry refusals. */
47
60
  export interface InsulaUsageTransport {
48
61
  connectionFile: string;
49
62
  getUsage(): Promise<unknown>;
63
+ /**
64
+ * Open a `usage.watch` stream, passing each notice's raw JSON body to
65
+ * `onNotice`. Optional: a transport without it is polled as before.
66
+ */
67
+ watchUsage?(onNotice: (body: Uint8Array) => void): InsulaUsageWatch;
50
68
  }
51
69
  /** Constructing this transport opens no connection; getUsage opens one per call. */
52
70
  export declare function insulaUsageTransport(options: ClaustrumClientOptions & {
53
71
  connectionFile: string;
54
72
  }): InsulaUsageTransport;
73
+ export interface InsulaWatchOptions {
74
+ /**
75
+ * The provider this watcher reads. A notice that names only other
76
+ * providers then needs no read; unset means every notice does.
77
+ */
78
+ provider?: string;
79
+ /**
80
+ * setTimeout and clearTimeout for the waits before re-subscribing or retrying
81
+ * a watch. Defaults to the global timers; tests inject virtual ones.
82
+ */
83
+ setTimeoutImpl?: typeof setTimeout;
84
+ clearTimeoutImpl?: typeof clearTimeout;
85
+ }
55
86
  export declare class InsulaQuotaSource {
56
87
  #private;
57
88
  private readonly transport;
58
89
  private readonly key;
59
90
  constructor(transport: InsulaUsageTransport, key: string);
91
+ /**
92
+ * The background poll: at most one usage.get per minute per daemon and
93
+ * enrollment token. While a watch is open it reads nothing, because insula's
94
+ * notices announce every new reading. If insula stops announcing an account,
95
+ * that account's last entry grows older than the freshness limit `current()`
96
+ * applies, `current()` returns nothing for it, and the plugin falls back to
97
+ * its own provider poll for that account.
98
+ */
60
99
  refresh(now: number): Promise<void>;
100
+ /** How this source currently learns about usage changes, for logs. */
101
+ watchMode(): WatchMode;
102
+ /**
103
+ * Hold a `usage.watch` open while any watcher wants it, and re-read
104
+ * usage.get when a notice says something changed. Watchers of one source
105
+ * share one watch, since insula admits only 64 per process. Returns the
106
+ * release; the last release closes the watch.
107
+ */
108
+ watch(options?: InsulaWatchOptions): () => void;
61
109
  current(provider: string, accountId: string, now: number): {
62
110
  entry: InsulaUsageEntry;
63
111
  context: InsulaQuotaContext;
@@ -0,0 +1,141 @@
1
+ import type { ClaustrumLogger } from './errors.js';
2
+ /**
3
+ * How a host currently learns about changes, for logs and status displays.
4
+ * `watching`: a watch was accepted and is open, so polling is reduced to a
5
+ * slow safety read. `polling`: no watch is open yet (not started, opening, or
6
+ * re-subscribing after a close), so the host polls at its usual interval.
7
+ * `fallback`: the watch is unavailable (an older module or client, a refusal,
8
+ * the watch limit, or repeated failures), so the host polls at its usual
9
+ * interval and may try a watch again later. Never carries secrets.
10
+ */
11
+ export type WatchMode = 'watching' | 'polling' | 'fallback';
12
+ /**
13
+ * While a vault watch is healthy, the roster is still read this often: the
14
+ * watch carries no history, so a lost notice or a silently dead stream is
15
+ * caught within this period.
16
+ */
17
+ export declare const SAFETY_POLL_MS: number;
18
+ /**
19
+ * After a watch fails without being accepted, the host polls and tries one
20
+ * new watch this much later, so a refusing or draining module is never asked
21
+ * in a tight loop.
22
+ */
23
+ export declare const WATCH_RETRY_MS: number;
24
+ /**
25
+ * First wait before re-subscribing a watch that closed after it had been
26
+ * accepted. It doubles for each further close in a row, up to WATCH_RETRY_MS.
27
+ */
28
+ export declare const RESUBSCRIBE_BACKOFF_MS = 1000;
29
+ /**
30
+ * The fields every change notice carries, from the vault's watchScoped and
31
+ * insula's usage.watch alike.
32
+ */
33
+ export interface ChangeNotice {
34
+ readonly kind: string;
35
+ readonly epoch: string;
36
+ readonly seq: number;
37
+ }
38
+ /**
39
+ * Tells whether a notice follows the previous one with nothing lost between
40
+ * them. `seq` restarts at 1 for every watch and `epoch` names the sending
41
+ * module's process lifetime. A sequence gap (notices are sheddable), a
42
+ * different epoch (the module restarted) or a notice of an unknown kind all
43
+ * mean changes may have been missed, so the caller must re-read everything.
44
+ */
45
+ export declare class ChangeNoticeReader {
46
+ #private;
47
+ /**
48
+ * Begin a new watch, whose first notice is seq 1 again. The epoch is kept,
49
+ * so a module restart between two watches still reads as a break.
50
+ */
51
+ restart(): void;
52
+ continuous(notice: ChangeNotice): boolean;
53
+ }
54
+ /**
55
+ * Runs `read` with at most one call in flight and at most one more queued
56
+ * behind it, however many requests arrive meanwhile. A request made while a
57
+ * read is running may have arrived after that read took its snapshot, so it
58
+ * earns exactly one more read; any further requests share that one.
59
+ */
60
+ export declare class CoalescedRead {
61
+ #private;
62
+ constructor(read: () => Promise<void>, onError: (error: unknown) => void);
63
+ /** The read in flight (including its queued follow-up), if any. */
64
+ get running(): Promise<void> | undefined;
65
+ request(): Promise<void>;
66
+ }
67
+ /** A vault watch notice: `view` is the same digest `list_scoped` returns. */
68
+ export interface ScopedWatchNoticeShape extends ChangeNotice {
69
+ readonly view: string;
70
+ }
71
+ /**
72
+ * How a vault watch ended, as claustrum-client 0.12.0 reports it. `refused`
73
+ * and `not_accepting` both mean the watch closed before its first notice; the
74
+ * client then made one `list_scoped` read to learn why, and `refused` carries
75
+ * that read's refusal.
76
+ */
77
+ export type ScopedWatchEnd = {
78
+ readonly kind: 'refused';
79
+ readonly error: unknown;
80
+ } | {
81
+ readonly kind: 'transport_lost';
82
+ readonly error: unknown;
83
+ } | {
84
+ readonly kind: 'ended' | 'not_accepting' | 'unsupported' | 'stopped';
85
+ };
86
+ export interface ScopedWatchHandle {
87
+ stop(): void;
88
+ readonly closed: Promise<ScopedWatchEnd>;
89
+ }
90
+ /**
91
+ * The part of a vault client that can watch. claustrum-client added
92
+ * `watchScoped` in 0.12.0; the peer range still admits 0.6.2, so it is
93
+ * optional and detected at run time.
94
+ */
95
+ export interface ScopedWatchSource {
96
+ watchScoped?(onNotice: (notice: ScopedWatchNoticeShape) => void, options?: {
97
+ enrollmentToken?: string;
98
+ }): ScopedWatchHandle;
99
+ }
100
+ export interface ScopedRosterWatchOptions {
101
+ client: ScopedWatchSource;
102
+ /** The enrollment token, read again for every watch so a new one is used. */
103
+ enrollmentToken: () => Promise<string>;
104
+ /** The view of the roster this host last discovered; undefined for none. */
105
+ view: () => string | undefined;
106
+ /**
107
+ * The host's existing discovery: `list_scoped`, the roster commit and
108
+ * everything that follows it. The watch never reads the vault list itself.
109
+ * `view` is the view the newest notice carried.
110
+ */
111
+ discover: (view: string) => Promise<unknown>;
112
+ /**
113
+ * The vault refused the watch, and the confirming `list_scoped` read it
114
+ * with this error (a revoked enrollment ends both with `not_found`). Handle
115
+ * it as discovery handles the same refusal from `list_scoped`.
116
+ */
117
+ onRefused: (error: unknown) => void;
118
+ onTransportLost?: () => void;
119
+ onReachable?: () => void;
120
+ onError?: (error: unknown) => void;
121
+ onMode?: (mode: WatchMode) => void;
122
+ logger?: ClaustrumLogger;
123
+ now?: () => number;
124
+ setTimeoutImpl?: typeof setTimeout;
125
+ clearTimeoutImpl?: typeof clearTimeout;
126
+ }
127
+ /**
128
+ * Keeps one vault `watchScoped` open for a host and runs the host's discovery
129
+ * when a notice shows the visible account list changed. Discovery runs only
130
+ * when the notice's view differs from the last discovered roster's view, when
131
+ * a notice shows a gap or a new epoch, or on the first notice of a watch that
132
+ * was re-subscribed after a close (the time between two watches was not
133
+ * observed). It never opens a second watch while one is open.
134
+ */
135
+ export declare class ScopedRosterWatch {
136
+ #private;
137
+ constructor(options: ScopedRosterWatchOptions);
138
+ get mode(): WatchMode;
139
+ start(): void;
140
+ stop(): void;
141
+ }
@@ -13,7 +13,7 @@ export interface RefreshFileLock {
13
13
  whenLost(): Promise<LockLoss>;
14
14
  hasLost(): boolean;
15
15
  }
16
- export declare function acquireRefreshFileLock(options: {
16
+ type RefreshFileLockOptions = {
17
17
  name: string;
18
18
  ttlMs: number;
19
19
  /**
@@ -22,7 +22,6 @@ export declare function acquireRefreshFileLock(options: {
22
22
  * be one host's path.
23
23
  */
24
24
  path: string;
25
- now?: () => number;
26
25
  renew?: boolean;
27
26
  renewIntervalMs?: number;
28
27
  /** Notifies a live-owner refusal without awaiting; observer failures are ignored. */
@@ -30,4 +29,11 @@ export declare function acquireRefreshFileLock(options: {
30
29
  /** Synchronous, never awaited; throws and returned promise/thenable rejections are isolated. */
31
30
  onRenewalTimer?: (event: 'scheduled' | 'cancelled') => void;
32
31
  onStep?: (step: 'stale-marker-stat' | 'stale-marker-claimed' | 'stale-lock-observed' | 'lock-read-ready' | 'lock-missing' | 'stale-lock-confirmed' | 'stale-lock-removed' | 'stale-lock-recreated' | 'eviction-marker-acquired' | 'renewal-owner-confirmed' | 'renewal-marker-unavailable' | 'renewal-write-fenced' | 'renewal-write-ready' | 'renewal-write-finished' | 'relinquish-read' | 'renewal-finished' | 'release-owner-confirmed') => void | Promise<void>;
32
+ };
33
+ /** Filesystem leases share wall time across all callers and processes. */
34
+ export declare function acquireRefreshFileLock(options: RefreshFileLockOptions): Promise<RefreshFileLock | null>;
35
+ /** @internal Clock seam for lease tests; not exported by the package's fs entry point. */
36
+ export declare function acquireRefreshFileLockWithClock(options: RefreshFileLockOptions & {
37
+ now?: () => number;
33
38
  }): Promise<RefreshFileLock | null>;
39
+ export {};
@@ -11,8 +11,14 @@ export declare const NO_LIMITS_REPORTED = "no limits reported";
11
11
  /**
12
12
  * `compact` fits a footer or a sidebar row: each window's figure, the credit
13
13
  * budget and the stale marker, without reset times. `full` adds each reset.
14
+ * `narrow` fits one line per account in a narrow sidebar: `5h 92% · 7d 66%
15
+ * · Fa 98% left`, the account-wide windows plus at most one model-scoped
16
+ * window or the budget (as `cr`), and no stale marker (see `isQuotaStale`).
17
+ * A reading whose windows belong to named groups and that has no
18
+ * account-wide window reads up to two groups instead:
19
+ * `Ge 7d 62% · Ot 7d 48% left`.
14
20
  */
15
- export type QuotaTextForm = 'compact' | 'full';
21
+ export type QuotaTextForm = 'compact' | 'full' | 'narrow';
16
22
  export interface QuotaTextOptions {
17
23
  /** The current time in ms, for reset countdowns and the stale marker. */
18
24
  now: number;
@@ -55,17 +61,25 @@ export declare function quotaWindowName(limit: Pick<ProjectedLimit, 'scope' | 'l
55
61
  * and the optional age keep the shared formatter's wording.
56
62
  */
57
63
  export declare function quotaWindowParts(quota: ProjectedQuota | undefined, options: QuotaTextOptions): QuotaParts;
64
+ /**
65
+ * Whether the reading is stale: true exactly when the compact and full forms
66
+ * would end with `checked … ago`. The narrow form leaves that age out to stay
67
+ * short, so a caller drawing a narrow line uses this to dim it instead.
68
+ */
69
+ export declare function isQuotaStale(quota: ProjectedQuota | undefined, options: QuotaTextOptions): boolean;
58
70
  /**
59
71
  * The pieces of a quota text, in order: one per reported window
60
72
  * (`5h 58% left, resets 2h`), then the credit budget when there is one, then
61
73
  * `checked 3h ago` when the oldest piece shown is stale. Empty when nothing
62
74
  * was reported; `formatQuota` turns that into a sentence. A caller printing
63
- * one line per window (the terminal auth menu) uses these directly.
75
+ * one line per window (the terminal auth menu) uses these directly. In the
76
+ * narrow form the pieces are the narrow line's (`5h 92%`, `7d 66% left`).
64
77
  */
65
78
  export declare function quotaTextParts(quota: ProjectedQuota | undefined, options: QuotaTextOptions): string[];
66
79
  /**
67
80
  * A row's quota as one line: `5h 58% left · 7d 90% left` in the compact
68
- * form, with `, resets 2h` after each window in the full form. With nothing
81
+ * form, with `, resets 2h` after each window in the full form, and
82
+ * `5h 58% · 7d 90% left` in the narrow form. With nothing
69
83
  * reported it is `NO_QUOTA_READING`, or `NO_LIMITS_REPORTED` when the
70
84
  * provider answered without a limit for any window.
71
85
  */
@@ -1,10 +1,10 @@
1
1
  export type { QuotaCodec } from './codec.js';
2
2
  export { quotaCodec } from './codec.js';
3
3
  export type { QuotaParts, QuotaTextForm, QuotaTextOptions, QuotaWindowPart, } from './format.js';
4
- export { formatQuota, NO_LIMITS_REPORTED, NO_QUOTA_READING, QUOTA_STALE_AFTER_MS, quotaTextParts, quotaWindowName, quotaWindowParts, } from './format.js';
4
+ export { formatQuota, isQuotaStale, NO_LIMITS_REPORTED, NO_QUOTA_READING, QUOTA_STALE_AFTER_MS, quotaTextParts, quotaWindowName, quotaWindowParts, } from './format.js';
5
5
  export type { CreditBudgetCleared, CreditBudgetEntry, CreditBudgetReading, QuotaAbsentEntry, QuotaCounter, QuotaEntry, QuotaMap, QuotaReadingEntry, QuotaRetiredEntry, } from './map.js';
6
6
  export { ALL_SCOPE, DEFAULT_REQUIRED_LABELS, decodeQuotaMap, emptyQuotaMap, isQuotaMap, } from './map.js';
7
7
  export type { ObservedBudget, ObservedPair, ObservedReading, QuotaObservation, } from './merge.js';
8
8
  export { isQuotaObservation, mergeQuotaObservation, QuotaCodecError, } from './merge.js';
9
- export type { ExhaustionReset, ProjectedBudget, ProjectedLimit, ProjectedQuota, } from './projection.js';
9
+ export type { ExhaustionReset, ProjectedBudget, ProjectedLimit, ProjectedQuota, QuotaGroup, } from './projection.js';
10
10
  export { budgetExhaustedResetAt, futureResetAt, projectQuota, readsExhausted, } from './projection.js';
@@ -19,6 +19,15 @@ export interface ProjectedBudget {
19
19
  remainingPercent?: number;
20
20
  resetsAt?: string;
21
21
  }
22
+ /**
23
+ * A named group of windows, such as antigravity-auth's `Gemini` and
24
+ * `Other models`: every window stored under `scope` belongs to it, and
25
+ * `label` is the group's display name.
26
+ */
27
+ export interface QuotaGroup {
28
+ scope: string;
29
+ label: string;
30
+ }
22
31
  export interface ProjectedQuota {
23
32
  scope: string;
24
33
  /** One entry per label: longest known window first, unknown lengths last. */
@@ -31,6 +40,13 @@ export interface ProjectedQuota {
31
40
  /** Present only when the stored budget is a reading, not cleared. */
32
41
  budget?: ProjectedBudget;
33
42
  counters?: Record<string, QuotaCounter>;
43
+ /**
44
+ * The named groups the windows belong to, in the order the plugin lists
45
+ * them. Set only by a plugin whose windows all belong to such groups; the
46
+ * narrow form then shows one item per group (see `formatQuota`).
47
+ * `projectQuota` never sets it.
48
+ */
49
+ groups?: readonly QuotaGroup[];
34
50
  }
35
51
  /**
36
52
  * Resolves `map` for a request in `scope` (`all` or a model family). A family
@@ -0,0 +1,32 @@
1
+ import type { SetupHostEnrollment } from './types.js';
2
+ /**
3
+ * Keeps the Pi install refusal message stable while exposing safe process details.
4
+ * A clipped tail can start inside a credential, so discard its first line—or
5
+ * the whole tail if it has no newline—before redacting.
6
+ */
7
+ export declare class SetupCommandError extends Error {
8
+ readonly step = "pi-install";
9
+ readonly exitCode: number | null;
10
+ readonly signal: string | null;
11
+ readonly stderrTail: string;
12
+ constructor(details: {
13
+ exitCode: number | null;
14
+ signal: string | null;
15
+ stderrTail: string;
16
+ stderrTruncated?: boolean;
17
+ });
18
+ }
19
+ /** The line setup prints for one host's outcome, e.g. `Pi: not connected`. */
20
+ export declare function setupEnrollmentLine({ host, outcome, }: SetupHostEnrollment): string;
21
+ /**
22
+ * Remember which hosts a failed setup left connected to the vault, against the
23
+ * thrown value. Only objects can carry a record; a thrown primitive is left as
24
+ * it is, and the printed lines are then the only report.
25
+ */
26
+ export declare function recordSetupEnrollment(failure: unknown, enrollment: readonly SetupHostEnrollment[]): void;
27
+ /**
28
+ * The per-host vault enrollment outcomes a failed `runSetup` recorded for the
29
+ * value it threw, or `undefined` when setup failed before any host's enrollment
30
+ * began, or the value is not one setup threw (or is not an object).
31
+ */
32
+ export declare function setupEnrollment(error: unknown): readonly SetupHostEnrollment[] | undefined;
@@ -1,5 +1,6 @@
1
1
  export { AMBIGUOUS_OPENCODE_MESSAGE, runSetup } from './command.js';
2
+ export { SetupCommandError, setupEnrollment } from './command-error.js';
2
3
  export { detectHosts, detectOpenCodeGeneration, findExecutableOnPath, openCodeDesktopMarkers, } from './detect.js';
3
4
  export { assertHostsStopped, createProcessFence, listSetupProcesses, ProcessFenceViolationError, ProcessInspectionError, type ProcessInspectionStep, } from './process-fence.js';
4
5
  export { type PlannedWrite, planOpenCodeRegistration, registerOpenCode, registerPi, updatePluginConfig, } from './register.js';
5
- export type { CommandResult, CommandRunner, HostDetection, OpenCodeGeneration, ProcessFence, SetupCallbackContext, SetupDetection, SetupEnvironment, SetupFileSystem, SetupHost, SetupIO, SetupPlugin, SetupResult, } from './types.js';
6
+ export type { CommandResult, CommandRunner, HostDetection, OpenCodeGeneration, ProcessFence, SetupCallbackContext, SetupDetection, SetupEnrollmentOutcome, SetupEnvironment, SetupFileSystem, SetupHost, SetupHostEnrollment, SetupIO, SetupPlugin, SetupResult, } from './types.js';
@@ -3,6 +3,18 @@ import type { ClaustrumEnrollmentConnection, hostEnrollmentPaths } from '../clau
3
3
  export type SetupHost = 'opencode' | 'pi';
4
4
  export type OpenCodeGeneration = '1' | '2' | 'both';
5
5
  export type SetupEnvironment = Record<string, string | undefined>;
6
+ /**
7
+ * What a setup run recorded about one host's vault enrollment when it failed:
8
+ * `enrolled` once approval landed and the token was written, `not-enrolled`
9
+ * when the host was never asked or its enrollment was refused or gave up
10
+ * waiting, and `unknown` when setup failed while the enrollment was still in
11
+ * flight and the host's token file could not settle it.
12
+ */
13
+ export type SetupEnrollmentOutcome = 'enrolled' | 'not-enrolled' | 'unknown';
14
+ export interface SetupHostEnrollment {
15
+ host: SetupHost;
16
+ outcome: SetupEnrollmentOutcome;
17
+ }
6
18
  /**
7
19
  * What setup decided before calling a plugin callback. The OpenCode generation
8
20
  * is the one being registered, after `--opencode` or the interactive choice, so
@@ -57,6 +69,8 @@ export interface CommandResult {
57
69
  exitCode: number;
58
70
  stdout: string;
59
71
  stderr: string;
72
+ spawnError?: boolean;
73
+ stderrTruncated?: boolean;
60
74
  signal?: NodeJS.Signals | null;
61
75
  timedOut?: boolean;
62
76
  durationMs?: number;