@cortexkit/opencode-antigravity-auth 3.0.7 → 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 (118) hide show
  1. package/dist/cli.js +1001 -63
  2. package/dist/cli.js.map +4 -4
  3. package/dist/cli.meta.json +112 -30
  4. package/dist/index.js +1270 -219
  5. package/dist/index.js.map +4 -4
  6. package/dist/index.meta.json +154 -48
  7. package/dist/server.js +1190 -120
  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 +31 -1
  13. package/dist/src/common-auth-embedded/claustrum/consumer.js +114 -5
  14. package/dist/src/common-auth-embedded/claustrum/custody.d.ts +106 -14
  15. package/dist/src/common-auth-embedded/claustrum/custody.js +294 -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/quota/format.d.ts +3 -0
  25. package/dist/src/common-auth-embedded/quota/format.js +69 -1
  26. package/dist/src/common-auth-embedded/quota/index.d.ts +1 -1
  27. package/dist/src/common-auth-embedded/quota/projection.d.ts +16 -0
  28. package/dist/src/common-auth-embedded/source-output.json +81 -49
  29. package/dist/src/ga/server/index.d.ts +2 -0
  30. package/dist/src/ga/server/index.d.ts.map +1 -1
  31. package/dist/src/ga/server/index.js +14 -1
  32. package/dist/src/ga/server/index.js.map +1 -1
  33. package/dist/src/plugin/auth-loader.d.ts +2 -1
  34. package/dist/src/plugin/auth-loader.d.ts.map +1 -1
  35. package/dist/src/plugin/auth-loader.js +5 -4
  36. package/dist/src/plugin/auth-loader.js.map +1 -1
  37. package/dist/src/plugin/fetch-interceptor.d.ts +2 -1
  38. package/dist/src/plugin/fetch-interceptor.d.ts.map +1 -1
  39. package/dist/src/plugin/fetch-interceptor.js +8 -6
  40. package/dist/src/plugin/fetch-interceptor.js.map +1 -1
  41. package/dist/src/plugin/ga-location-services.d.ts.map +1 -1
  42. package/dist/src/plugin/ga-location-services.js +3 -0
  43. package/dist/src/plugin/ga-location-services.js.map +1 -1
  44. package/dist/src/plugin/shared/after-handoff.d.ts +14 -0
  45. package/dist/src/plugin/shared/after-handoff.d.ts.map +1 -0
  46. package/dist/src/plugin/shared/after-handoff.js +89 -0
  47. package/dist/src/plugin/shared/after-handoff.js.map +1 -0
  48. package/dist/src/plugin/shared/request-services.d.ts +8 -2
  49. package/dist/src/plugin/shared/request-services.d.ts.map +1 -1
  50. package/dist/src/plugin/shared/request-services.js +57 -36
  51. package/dist/src/plugin/shared/request-services.js.map +1 -1
  52. package/dist/src/plugin/shared/vault-request-credentials.d.ts +2 -2
  53. package/dist/src/plugin/shared/vault-request-credentials.d.ts.map +1 -1
  54. package/dist/src/plugin/shared/vault-request-credentials.js +14 -1
  55. package/dist/src/plugin/shared/vault-request-credentials.js.map +1 -1
  56. package/dist/src/plugin/vault-custody.d.ts +2 -0
  57. package/dist/src/plugin/vault-custody.d.ts.map +1 -1
  58. package/dist/src/plugin/vault-custody.js +3 -0
  59. package/dist/src/plugin/vault-custody.js.map +1 -1
  60. package/dist/src/tui.d.ts.map +1 -1
  61. package/dist/src/tui.js +82 -66
  62. package/dist/src/tui.js.map +1 -1
  63. package/dist/tui-build-map.json +27 -27
  64. package/dist/tui-ga-build-map.json +5 -5
  65. package/dist/types/src/common-auth-embedded/claustrum/availability.d.ts +89 -0
  66. package/dist/types/src/common-auth-embedded/claustrum/consumer.d.ts +31 -1
  67. package/dist/types/src/common-auth-embedded/claustrum/custody.d.ts +106 -14
  68. package/dist/types/src/common-auth-embedded/claustrum/errors.d.ts +1 -0
  69. package/dist/types/src/common-auth-embedded/claustrum/index.d.ts +5 -3
  70. package/dist/types/src/common-auth-embedded/claustrum/insula.d.ts +48 -0
  71. package/dist/types/src/common-auth-embedded/claustrum/watch.d.ts +141 -0
  72. package/dist/types/src/common-auth-embedded/quota/format.d.ts +3 -0
  73. package/dist/types/src/common-auth-embedded/quota/index.d.ts +1 -1
  74. package/dist/types/src/common-auth-embedded/quota/projection.d.ts +16 -0
  75. package/dist/types/src/ga/server/index.d.ts +2 -0
  76. package/dist/types/src/ga/server/index.d.ts.map +1 -1
  77. package/dist/types/src/plugin/auth-loader.d.ts +2 -1
  78. package/dist/types/src/plugin/auth-loader.d.ts.map +1 -1
  79. package/dist/types/src/plugin/fetch-interceptor.d.ts +2 -1
  80. package/dist/types/src/plugin/fetch-interceptor.d.ts.map +1 -1
  81. package/dist/types/src/plugin/ga-location-services.d.ts.map +1 -1
  82. package/dist/types/src/plugin/shared/after-handoff.d.ts +14 -0
  83. package/dist/types/src/plugin/shared/after-handoff.d.ts.map +1 -0
  84. package/dist/types/src/plugin/shared/request-services.d.ts +8 -2
  85. package/dist/types/src/plugin/shared/request-services.d.ts.map +1 -1
  86. package/dist/types/src/plugin/shared/vault-request-credentials.d.ts +2 -2
  87. package/dist/types/src/plugin/shared/vault-request-credentials.d.ts.map +1 -1
  88. package/dist/types/src/plugin/vault-custody.d.ts +2 -0
  89. package/dist/types/src/plugin/vault-custody.d.ts.map +1 -1
  90. package/package.json +4 -4
  91. package/src/common-auth-embedded/claustrum/availability.d.ts +89 -0
  92. package/src/common-auth-embedded/claustrum/availability.js +106 -0
  93. package/src/common-auth-embedded/claustrum/consumer.d.ts +31 -1
  94. package/src/common-auth-embedded/claustrum/consumer.js +114 -5
  95. package/src/common-auth-embedded/claustrum/custody.d.ts +106 -14
  96. package/src/common-auth-embedded/claustrum/custody.js +294 -16
  97. package/src/common-auth-embedded/claustrum/errors.d.ts +1 -0
  98. package/src/common-auth-embedded/claustrum/index.d.ts +5 -3
  99. package/src/common-auth-embedded/claustrum/index.js +4 -1
  100. package/src/common-auth-embedded/claustrum/insula.d.ts +48 -0
  101. package/src/common-auth-embedded/claustrum/insula.js +286 -21
  102. package/src/common-auth-embedded/claustrum/watch.d.ts +141 -0
  103. package/src/common-auth-embedded/claustrum/watch.js +254 -0
  104. package/src/common-auth-embedded/fs/private-files.js +10 -2
  105. package/src/common-auth-embedded/quota/format.d.ts +3 -0
  106. package/src/common-auth-embedded/quota/format.js +69 -1
  107. package/src/common-auth-embedded/quota/index.d.ts +1 -1
  108. package/src/common-auth-embedded/quota/projection.d.ts +16 -0
  109. package/src/common-auth-embedded/source-output.json +81 -49
  110. package/src/tui-compiled/common-auth-embedded/fs/private-files.js +10 -2
  111. package/src/tui-compiled/common-auth-embedded/quota/format.js +69 -1
  112. package/src/tui-compiled/tui.js +123 -97
  113. package/src/tui-ga-compiled/shared/aef2402f8fc342f0-format.js +69 -1
  114. package/src/tui-ga-raw/shared/aef2402f8fc342f0-format.js +69 -1
  115. package/src/tui-raw/common-auth-embedded/fs/private-files.js +10 -2
  116. package/src/tui-raw/common-auth-embedded/quota/format.js +69 -1
  117. package/src/tui-raw/tui.tsx +126 -107
  118. package/src/tui.tsx +126 -107
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schema": 1,
3
- "compiler": "@cortexkit/common-auth/tui-build@0.19.0",
3
+ "compiler": "@cortexkit/common-auth/tui-build@0.21.1",
4
4
  "bun": "1.4.2",
5
5
  "raw": {
6
6
  "selector": "selector.js",
@@ -40,8 +40,8 @@
40
40
  {
41
41
  "source": "src/common-auth-embedded/quota/format.js",
42
42
  "output": "src/tui-raw/common-auth-embedded/quota/format.js",
43
- "bytes": 12897,
44
- "sha256": "77bca99751555d6d5895a00d3601bf5a3c3b4aa7cfc1aa36d2931ba4d1eb9173",
43
+ "bytes": 16323,
44
+ "sha256": "ffa9cb0a06d952e6bf258928dcbbe9e446c5fc7e7b3d57e8e226a365bd220f2d",
45
45
  "transform": "public-raw"
46
46
  },
47
47
  {
@@ -58,13 +58,6 @@
58
58
  "sha256": "4567b82cc19673867983e53939f2e69daadd49ecf6174a3be180e7780a4bf889",
59
59
  "transform": "public-raw"
60
60
  },
61
- {
62
- "source": "src/quota-presentation.ts",
63
- "output": "src/tui-raw/quota-presentation.js",
64
- "bytes": 2428,
65
- "sha256": "1db4a0acf6381406e220f88a8c89698fa33ca9fda9318fa38b7baed92c8acef6",
66
- "transform": "public-raw"
67
- },
68
61
  {
69
62
  "source": "src/rpc/rpc-dir.ts",
70
63
  "output": "src/tui-raw/rpc/rpc-dir.js",
@@ -89,8 +82,8 @@
89
82
  {
90
83
  "source": "src/common-auth-embedded/fs/private-files.js",
91
84
  "output": "src/tui-raw/common-auth-embedded/fs/private-files.js",
92
- "bytes": 12025,
93
- "sha256": "a550d91f9dd95021fee2596fcdb2a47633adef6461ce0dea35bdd7bba3e83be5",
85
+ "bytes": 12448,
86
+ "sha256": "004b99daba0df2ce0aa43f21678e13242612966751035dd2459cd69866dadb52",
94
87
  "transform": "public-raw"
95
88
  },
96
89
  {
@@ -177,6 +170,13 @@
177
170
  "sha256": "db04199203d3e9d850ca4f0882548cfdb8e9125cd8c760bf79a4462d174b3226",
178
171
  "transform": "public-raw"
179
172
  },
173
+ {
174
+ "source": "src/quota-presentation.ts",
175
+ "output": "src/tui-raw/quota-presentation.js",
176
+ "bytes": 2428,
177
+ "sha256": "1db4a0acf6381406e220f88a8c89698fa33ca9fda9318fa38b7baed92c8acef6",
178
+ "transform": "public-raw"
179
+ },
180
180
  {
181
181
  "source": "src/tui/quota-layout.tsx",
182
182
  "output": "src/tui-raw/tui/quota-layout.tsx",
@@ -201,8 +201,8 @@
201
201
  {
202
202
  "source": "src/tui.tsx",
203
203
  "output": "src/tui-raw/tui.tsx",
204
- "bytes": 36083,
205
- "sha256": "94d0a587dab906ade526ea73eae261b792a31c5c4319ee6189c1a7e3954b79b0",
204
+ "bytes": 36632,
205
+ "sha256": "ed13a5a3f5e9a8dd33b2aedf675286a9662bb71d3cbd659bf93eab5042e6246d",
206
206
  "transform": "public-raw"
207
207
  },
208
208
  {
@@ -248,8 +248,8 @@
248
248
  {
249
249
  "source": "src/common-auth-embedded/quota/format.js",
250
250
  "output": "src/tui-compiled/common-auth-embedded/quota/format.js",
251
- "bytes": 12897,
252
- "sha256": "77bca99751555d6d5895a00d3601bf5a3c3b4aa7cfc1aa36d2931ba4d1eb9173",
251
+ "bytes": 16323,
252
+ "sha256": "ffa9cb0a06d952e6bf258928dcbbe9e446c5fc7e7b3d57e8e226a365bd220f2d",
253
253
  "transform": "public-solid-runtime"
254
254
  },
255
255
  {
@@ -266,13 +266,6 @@
266
266
  "sha256": "4567b82cc19673867983e53939f2e69daadd49ecf6174a3be180e7780a4bf889",
267
267
  "transform": "public-solid-runtime"
268
268
  },
269
- {
270
- "source": "src/quota-presentation.ts",
271
- "output": "src/tui-compiled/quota-presentation.js",
272
- "bytes": 2428,
273
- "sha256": "1db4a0acf6381406e220f88a8c89698fa33ca9fda9318fa38b7baed92c8acef6",
274
- "transform": "public-solid-runtime"
275
- },
276
269
  {
277
270
  "source": "src/rpc/rpc-dir.ts",
278
271
  "output": "src/tui-compiled/rpc/rpc-dir.js",
@@ -297,8 +290,8 @@
297
290
  {
298
291
  "source": "src/common-auth-embedded/fs/private-files.js",
299
292
  "output": "src/tui-compiled/common-auth-embedded/fs/private-files.js",
300
- "bytes": 12025,
301
- "sha256": "a550d91f9dd95021fee2596fcdb2a47633adef6461ce0dea35bdd7bba3e83be5",
293
+ "bytes": 12448,
294
+ "sha256": "004b99daba0df2ce0aa43f21678e13242612966751035dd2459cd69866dadb52",
302
295
  "transform": "public-solid-runtime"
303
296
  },
304
297
  {
@@ -385,6 +378,13 @@
385
378
  "sha256": "b658119ee1ba6a7ab8b97c51600078dc1430a1d373a3092fb74b395830eb69b4",
386
379
  "transform": "public-solid-runtime"
387
380
  },
381
+ {
382
+ "source": "src/quota-presentation.ts",
383
+ "output": "src/tui-compiled/quota-presentation.js",
384
+ "bytes": 2428,
385
+ "sha256": "1db4a0acf6381406e220f88a8c89698fa33ca9fda9318fa38b7baed92c8acef6",
386
+ "transform": "public-solid-runtime"
387
+ },
388
388
  {
389
389
  "source": "src/tui/quota-layout.tsx",
390
390
  "output": "src/tui-compiled/tui/quota-layout.js",
@@ -409,8 +409,8 @@
409
409
  {
410
410
  "source": "src/tui.tsx",
411
411
  "output": "src/tui-compiled/tui.js",
412
- "bytes": 38917,
413
- "sha256": "47ef484fc3bf7834bc1a98d54aa778a98538a908e483506ee4b3cf79ffacb882",
412
+ "bytes": 39922,
413
+ "sha256": "bbc6c4f668abe7359a7cee9667dd1a3b787d5600248069be2ff97866e3b9cc22",
414
414
  "transform": "public-solid-runtime"
415
415
  },
416
416
  {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schema": 1,
3
- "compiler": "@cortexkit/common-auth/tui-build@0.19.0",
3
+ "compiler": "@cortexkit/common-auth/tui-build@0.21.1",
4
4
  "bun": "1.4.2",
5
5
  "raw": {
6
6
  "selector": "selector.js",
@@ -33,8 +33,8 @@
33
33
  {
34
34
  "source": "src/common-auth-embedded/quota/format.js",
35
35
  "output": "src/tui-ga-raw/shared/aef2402f8fc342f0-format.js",
36
- "bytes": 12914,
37
- "sha256": "69b2e4b36130a7b209d98387e1287a218377a77a96b82c2f9a57d6931c978d9b",
36
+ "bytes": 16340,
37
+ "sha256": "ae8be4fb26c87778c2869706021caccd5460cf13723cee1afa36db2dfb361caf",
38
38
  "transform": "public-raw"
39
39
  },
40
40
  {
@@ -137,8 +137,8 @@
137
137
  {
138
138
  "source": "src/common-auth-embedded/quota/format.js",
139
139
  "output": "src/tui-ga-compiled/shared/aef2402f8fc342f0-format.js",
140
- "bytes": 12914,
141
- "sha256": "69b2e4b36130a7b209d98387e1287a218377a77a96b82c2f9a57d6931c978d9b",
140
+ "bytes": 16340,
141
+ "sha256": "ae8be4fb26c87778c2869706021caccd5460cf13723cee1afa36db2dfb361caf",
142
142
  "transform": "public-solid-runtime"
143
143
  },
144
144
  {
@@ -0,0 +1,89 @@
1
+ import { ClaustrumConsumerError } from './errors.js';
2
+ export type VaultFailureClass = 'unreachable' | 'answered';
3
+ /**
4
+ * Codes from claustrum-client's decoder and its subc transport. A retry action
5
+ * alone is not evidence of an outage: even transient vault refusals must win
6
+ * over a previously served credential. New codes fail closed until reviewed.
7
+ */
8
+ export declare const VAULT_FAILURE_CLASSES: Readonly<{
9
+ ECONNREFUSED: "unreachable";
10
+ ENOENT: "unreachable";
11
+ ECONNRESET: "unreachable";
12
+ EPIPE: "unreachable";
13
+ ETIMEDOUT: "unreachable";
14
+ transport_error: "unreachable";
15
+ unavailable: "unreachable";
16
+ timeout: "unreachable";
17
+ route_closed: "unreachable";
18
+ daemon_draining: "unreachable";
19
+ connection_closed: "unreachable";
20
+ connection_dropped: "unreachable";
21
+ request_deadline: "unreachable";
22
+ deadline_exceeded_no_drop_observed: "unreachable";
23
+ module_reloading: "unreachable";
24
+ module_warming: "unreachable";
25
+ target_unavailable: "unreachable";
26
+ module_timeout: "unreachable";
27
+ invalid_response: "answered";
28
+ invalid_record_version: "answered";
29
+ invalid_expiry: "answered";
30
+ invalid_status: "answered";
31
+ invalid_params: "answered";
32
+ ttl_unsatisfiable: "answered";
33
+ not_found: "answered";
34
+ enrollment_revoked: "answered";
35
+ enrollment_invalid: "answered";
36
+ grant_denied: "answered";
37
+ credential_unavailable: "answered";
38
+ needs_reauth: "answered";
39
+ declined: "answered";
40
+ disabled: "answered";
41
+ identity_changed: "answered";
42
+ closed: "answered";
43
+ client_closed: "answered";
44
+ pending_exists: "answered";
45
+ pending_queue_full: "answered";
46
+ already_consumed: "answered";
47
+ superseded: "answered";
48
+ stale_generation: "answered";
49
+ missing_identity: "answered";
50
+ invalid_control_body: "answered";
51
+ unknown_module: "answered";
52
+ module_removed: "answered";
53
+ capability_denied: "answered";
54
+ unknown_channel: "unreachable";
55
+ stale_route_epoch: "unreachable";
56
+ capability_forbidden: "answered";
57
+ capability_unprovided: "answered";
58
+ capability_ambiguous: "answered";
59
+ invalid_capability_identifier: "answered";
60
+ binary_body_required: "answered";
61
+ binary_call_requires_call_binary: "answered";
62
+ corr_exhausted: "answered";
63
+ late_route_cleanup_failed: "answered";
64
+ reverse_request_capability_not_declared: "answered";
65
+ stale_route_handle: "answered";
66
+ reverse_request_unhandled: "answered";
67
+ handler_error: "answered";
68
+ health_error: "answered";
69
+ duplicate_module_id: "answered";
70
+ route_rejected: "answered";
71
+ lock_busy: "answered";
72
+ owner_invalid: "answered";
73
+ renewal_failed: "answered";
74
+ unsupported_platform: "answered";
75
+ EACCES: "answered";
76
+ EPERM: "answered";
77
+ ERR_PRIVATE_FILES_SECURITY: "answered";
78
+ }>;
79
+ /**
80
+ * An injected adapter may throw this ONLY when its connection/transport is
81
+ * unreachable, including a failed connect before getScoped. Do not wrap an
82
+ * adapter shutdown, cancellation, validation error or vault refusal in it.
83
+ * Its fixed message cannot echo enrollment or credential material, and its
84
+ * kind stays `unavailable` for callers handling ClaustrumConsumerError.
85
+ */
86
+ export declare class ClaustrumUnreachableError extends ClaustrumConsumerError {
87
+ constructor();
88
+ }
89
+ export declare function classifyVaultFailure(error: unknown): VaultFailureClass;
@@ -1,10 +1,11 @@
1
1
  import type { ClaustrumReporterSource } from '@cortexkit/claustrum-client';
2
2
  import type { QuotaObservation } from '../quota/index.js';
3
3
  import type { RoutingRow } from '../routing/index.js';
4
- import { type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, type IdentityParser, type VaultGrantReach } from './custody.js';
4
+ import { type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, type IdentityParser, type KeptReceiptState, type VaultGrantReach } from './custody.js';
5
5
  import { type ClaustrumLogger } from './errors.js';
6
6
  import { type InsulaQuotaOptions } from './insula.js';
7
7
  import { type AccountMapper, type QuotaReceipt, type VaultRosterFile } from './roster.js';
8
+ import { type WatchMode } from './watch.js';
8
9
  export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
9
10
  /**
10
11
  * The roster file: one row per vault account (route id, credential id,
@@ -41,6 +42,12 @@ export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
41
42
  */
42
43
  onRoster?: (roster: VaultRosterFile) => void;
43
44
  onError?: (error: unknown) => void;
45
+ /**
46
+ * How often `start()` ticks. A tick lists the vault when no vault watch is
47
+ * open (before it is accepted, or when the vault or the client cannot
48
+ * watch), and otherwise only every five minutes, as a safety net. A tick
49
+ * polls insula (at most once a minute) only while its watch is not open.
50
+ */
44
51
  pollIntervalMs?: number;
45
52
  setTimeoutImpl?: typeof setTimeout;
46
53
  clearTimeoutImpl?: typeof clearTimeout;
@@ -49,6 +56,15 @@ export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
49
56
  /** Optional background quota source. In-band readings still use recordQuota. */
50
57
  insula?: InsulaQuotaOptions<Q>;
51
58
  }
59
+ /**
60
+ * How a started consumer learns about changes, for logs and status displays.
61
+ * `insula` is present when the consumer was given an insula source. Never
62
+ * carries secrets.
63
+ */
64
+ export interface ClaustrumWatchState {
65
+ readonly vault: WatchMode;
66
+ readonly insula?: WatchMode;
67
+ }
52
68
  export interface SendOptions {
53
69
  /**
54
70
  * What kind of request this is (for example `model`, `quota`, `profile`),
@@ -81,9 +97,23 @@ export declare class ClaustrumConsumer<Q = QuotaObservation> {
81
97
  * held the discovery lease and its newer roster was served instead).
82
98
  */
83
99
  grantReach(): VaultGrantReach | undefined;
100
+ /** How this consumer currently learns about changes, without I/O. */
101
+ watchState(): ClaustrumWatchState;
102
+ /** Whether any account is using an in-memory outage receipt, without I/O. */
103
+ keptReceiptState(): KeptReceiptState;
84
104
  /** Rows for `/routing`, from the last committed roster. */
85
105
  routingRows(): RoutingRow[];
86
106
  refresh(): Promise<VaultRosterFile | undefined>;
107
+ /**
108
+ * Poll in the background and open the vault and insula watches. Until the
109
+ * vault watch is accepted, and whenever it is unavailable, every tick lists
110
+ * the vault exactly as before watches existed. While it is open a tick
111
+ * lists only when five minutes have passed since the last discovery, since
112
+ * the watch keeps no history; it still checks `isCustodyActive`, so a switch
113
+ * to local mode closes the connection as quickly as before. Insula is
114
+ * polled on the tick only while its own watch is not open. A host not in
115
+ * vault mode makes no request.
116
+ */
87
117
  start(): void;
88
118
  /**
89
119
  * Fetch on a background tick, at most once per minute across projects with
@@ -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
  /**
@@ -132,6 +137,57 @@ export interface ClaustrumScopedAttempt {
132
137
  readonly accessToken: string;
133
138
  readonly recordVersion: number;
134
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;
135
191
  }
136
192
  /** Reads the provider identity a served token executes under, when the plugin can tell. */
137
193
  export type IdentityParser = (accessToken: string) => string | undefined;
@@ -151,13 +207,15 @@ export declare function decideScopedRetryAfter401(site: string, served: Claustru
151
207
  * so it cannot expire while a long request is still using it.
152
208
  */
153
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;
154
212
  /**
155
213
  * Reads this consumer's vault credentials (list, fetch, 401 report), with the
156
- * enrollment token as authorization. Used by every host of a plugin. There is
157
- * deliberately no credential cache and no single-flight of credential reads:
158
- * each physical send is authorized by the vault, so a revoked enrollment or a
159
- * changed record takes effect on the next send. The enrollment token is
160
- * 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.
161
219
  */
162
220
  export declare class ClaustrumScopedCustody {
163
221
  #private;
@@ -177,7 +235,13 @@ export declare class ClaustrumScopedCustody {
177
235
  requireAssertion?: boolean;
178
236
  now?: () => number;
179
237
  logger?: ClaustrumLogger;
238
+ setTimeoutImpl?: typeof setTimeout;
239
+ clearTimeoutImpl?: typeof clearTimeout;
180
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;
181
245
  /**
182
246
  * List this consumer's credentials. A record that cannot be used is skipped
183
247
  * and warned about rather than failing the whole list, so one bad record
@@ -186,15 +250,23 @@ export declare class ClaustrumScopedCustody {
186
250
  */
187
251
  discover(signal?: AbortSignal): Promise<VaultInventory>;
188
252
  /**
189
- * Fetch the credential for one physical send and wrap it in a fresh receipt.
190
- * The vault's served identity (or, without one, the plugin's parse of the
191
- * token) must equal the roster's when both are present. Without
192
- * `requireAssertion`, absence on either side proves nothing and does not
193
- * refuse; the receipt records what the vault asserted separately from what
194
- * the roster expected. With it, a reply that does not itself name the
195
- * 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.
196
257
  */
197
- 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>;
198
270
  /**
199
271
  * Report that a send this consumer actually made was rejected. Only a 401
200
272
  * is reported (the vault refuses 429, 402 and 5xx reports), addressed by
@@ -203,5 +275,25 @@ export declare class ClaustrumScopedCustody {
203
275
  * custody did not issue is refused rather than reported.
204
276
  */
205
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;
206
298
  close(): void;
207
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 VaultGrantReach, type VaultGrantTuple, 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;