@openllmsh/sdk 0.0.0-stage → 2.10.12-alpha.1

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 (245) hide show
  1. package/ARCHITECTURE.md +43 -0
  2. package/LICENSE +202 -0
  3. package/README.md +142 -2
  4. package/assets/openllm-light.svg +18 -0
  5. package/assets/openllm.svg +18 -0
  6. package/client/chat.ts +140 -0
  7. package/client/devices.ts +269 -0
  8. package/client/http.ts +72 -0
  9. package/client/index.ts +129 -0
  10. package/client/relay-mux.ts +547 -0
  11. package/client/types.ts +51 -0
  12. package/client/vault.ts +239 -0
  13. package/connect/chat.ts +58 -0
  14. package/connect/client.ts +240 -0
  15. package/connect/config.ts +47 -0
  16. package/connect/errors.ts +121 -0
  17. package/connect/index.ts +23 -0
  18. package/connect/oauth.ts +265 -0
  19. package/connect/routes.ts +234 -0
  20. package/connect/store.ts +107 -0
  21. package/mcp/handle.ts +24 -0
  22. package/mcp/index.ts +76 -0
  23. package/mcp/server.ts +319 -0
  24. package/mcp/tools/marketplace.ts +439 -0
  25. package/mcp/tools/memory-client.ts +297 -0
  26. package/mcp/tools/memory-config.ts +32 -0
  27. package/mcp/tools/memory.ts +369 -0
  28. package/mcp/tools/model-priority.ts +88 -0
  29. package/mcp/tools/openllm.ts +883 -0
  30. package/mcp/types.ts +28 -0
  31. package/openapi/call.ts +90 -0
  32. package/openapi/index.ts +8 -0
  33. package/openapi/openapi.json +80213 -0
  34. package/openapi/operations.ts +2075 -0
  35. package/package.json +39 -4
  36. package/protocol/CONTRIBUTING.md +21 -0
  37. package/protocol/README.md +134 -0
  38. package/protocol/access.ts +186 -0
  39. package/protocol/agent-prompt-text.ts +32 -0
  40. package/protocol/agent.ts +991 -0
  41. package/protocol/api-key-syntax.ts +105 -0
  42. package/protocol/assets/openllm-light.svg +18 -0
  43. package/protocol/assets/openllm.svg +18 -0
  44. package/protocol/audio.ts +29 -0
  45. package/protocol/auth.ts +142 -0
  46. package/protocol/changelog.ts +155 -0
  47. package/protocol/chat.ts +458 -0
  48. package/protocol/client-registry.ts +356 -0
  49. package/protocol/config.ts +345 -0
  50. package/protocol/control-channel.ts +115 -0
  51. package/protocol/cooldown-reason.ts +78 -0
  52. package/protocol/cost.ts +10 -0
  53. package/protocol/daemon-port.ts +31 -0
  54. package/protocol/daemon.ts +1524 -0
  55. package/protocol/default-chains.ts +66 -0
  56. package/protocol/device-state.ts +85 -0
  57. package/protocol/doctor-report-local.ts +443 -0
  58. package/protocol/doctor-report-policy.ts +119 -0
  59. package/protocol/doctor-report.ts +947 -0
  60. package/protocol/errors.ts +14 -0
  61. package/protocol/execution-selection.ts +141 -0
  62. package/protocol/hop-grant.ts +33 -0
  63. package/protocol/image-edit-parse.ts +263 -0
  64. package/protocol/images.ts +298 -0
  65. package/protocol/index.ts +74 -0
  66. package/protocol/inference-headers.ts +3 -0
  67. package/protocol/keepalive.ts +69 -0
  68. package/protocol/local-auth.ts +300 -0
  69. package/protocol/local-device-control.ts +133 -0
  70. package/protocol/local-provider.ts +288 -0
  71. package/protocol/local-session.ts +118 -0
  72. package/protocol/marketplace.ts +187 -0
  73. package/protocol/media-attempt.ts +81 -0
  74. package/protocol/media-bytes.ts +28 -0
  75. package/protocol/media-default.ts +357 -0
  76. package/protocol/media-dimensions.ts +132 -0
  77. package/protocol/media-input.ts +61 -0
  78. package/protocol/media-model.ts +142 -0
  79. package/protocol/media-option-issue.ts +90 -0
  80. package/protocol/media-types.ts +70 -0
  81. package/protocol/model-match.ts +1051 -0
  82. package/protocol/model-settings.ts +327 -0
  83. package/protocol/models.ts +767 -0
  84. package/protocol/mux.ts +722 -0
  85. package/protocol/plan-surface.ts +59 -0
  86. package/protocol/provider-models.ts +16 -0
  87. package/protocol/provider-status.ts +206 -0
  88. package/protocol/provider-tier.ts +67 -0
  89. package/protocol/provider-usage.ts +263 -0
  90. package/protocol/providers.ts +901 -0
  91. package/protocol/public-usage-index.ts +354 -0
  92. package/protocol/realtime-generated.ts +31 -0
  93. package/protocol/realtime.ts +324 -0
  94. package/protocol/registry-pointer.ts +118 -0
  95. package/protocol/relay.ts +702 -0
  96. package/protocol/replay-session.ts +11 -0
  97. package/protocol/responses.ts +280 -0
  98. package/protocol/semver.ts +182 -0
  99. package/protocol/setup-mode.ts +22 -0
  100. package/protocol/sha256-hex.ts +98 -0
  101. package/protocol/stats.ts +406 -0
  102. package/protocol/streaming.ts +19 -0
  103. package/protocol/subscription-daemon-floors.ts +33 -0
  104. package/protocol/subscription-provider-compat.ts +104 -0
  105. package/protocol/subscription-provider.ts +32 -0
  106. package/protocol/team-grant.ts +17 -0
  107. package/protocol/team-shareable.ts +61 -0
  108. package/protocol/transcription-encoding.ts +76 -0
  109. package/protocol/url-locality-dns.ts +37 -0
  110. package/protocol/url-locality.ts +288 -0
  111. package/protocol/usage-snapshots.ts +9 -0
  112. package/protocol/vendor-cli-install.ts +29 -0
  113. package/protocol/video-job-plan.ts +50 -0
  114. package/protocol/videos.ts +227 -0
  115. package/tsconfig.json +14 -0
  116. package/tunnel/ARCHITECTURE.md +111 -0
  117. package/tunnel/LICENSE +33 -0
  118. package/tunnel/README.md +45 -0
  119. package/tunnel/assets/openllm-light.svg +18 -0
  120. package/tunnel/assets/openllm.svg +18 -0
  121. package/tunnel/channel-envelope.ts +139 -0
  122. package/tunnel/codec.ts +191 -0
  123. package/tunnel/device-anchor.ts +229 -0
  124. package/tunnel/device-control.ts +118 -0
  125. package/tunnel/device-grant.ts +173 -0
  126. package/tunnel/fleet.ts +77 -0
  127. package/tunnel/index.ts +22 -0
  128. package/tunnel/mux.ts +580 -0
  129. package/tunnel/peer-link.ts +390 -0
  130. package/tunnel/rtc-auth.ts +415 -0
  131. package/tunnel/rtc-duplex.ts +187 -0
  132. package/tunnel/rtc-ice.ts +136 -0
  133. package/tunnel/secure.ts +1298 -0
  134. package/tunnel/stream-reset-error.ts +14 -0
  135. package/tunnel/streams.ts +1430 -0
  136. package/tunnel/team-grant.ts +302 -0
  137. package/tunnel/wire-bytes.ts +102 -0
  138. package/vault/ARCHITECTURE.md +470 -0
  139. package/vault/LICENSE +33 -0
  140. package/vault/api-key.ts +190 -0
  141. package/vault/argon2.ts +106 -0
  142. package/vault/cli-auth-seal.ts +157 -0
  143. package/vault/cred-seal.ts +146 -0
  144. package/vault/credential.ts +55 -0
  145. package/vault/crypto.ts +210 -0
  146. package/vault/daemon-attest.ts +229 -0
  147. package/vault/derive.ts +113 -0
  148. package/vault/device-access.ts +87 -0
  149. package/vault/device-anchor.ts +185 -0
  150. package/vault/device-control.ts +174 -0
  151. package/vault/handoff.ts +396 -0
  152. package/vault/index.ts +21 -0
  153. package/vault/passkey.ts +243 -0
  154. package/vault/phrase.ts +65 -0
  155. package/vault/pin.ts +153 -0
  156. package/vault/public-key-seal.ts +131 -0
  157. package/vault/seed.ts +272 -0
  158. package/vault/team.ts +355 -0
  159. package/vault/vault-item.ts +131 -0
  160. package/vault/vault-migrate-digest.ts +29 -0
  161. package/vault/wrapped.ts +77 -0
  162. package/wire/ARCHITECTURE.md +90 -0
  163. package/wire/CONTRIBUTING.md +19 -0
  164. package/wire/LICENSE +33 -0
  165. package/wire/README.md +51 -0
  166. package/wire/adapters/messages/anthropic-map.ts +37 -0
  167. package/wire/adapters/messages/index.ts +7 -0
  168. package/wire/adapters/messages/reasoning-from-items.ts +38 -0
  169. package/wire/adapters/messages/reasoning-signature.ts +243 -0
  170. package/wire/adapters/messages/request.ts +574 -0
  171. package/wire/adapters/messages/response.ts +215 -0
  172. package/wire/adapters/messages/streaming.ts +1027 -0
  173. package/wire/adapters/messages/usage.ts +43 -0
  174. package/wire/adapters/responses/index.ts +3 -0
  175. package/wire/adapters/responses/request.ts +395 -0
  176. package/wire/adapters/responses/response.ts +88 -0
  177. package/wire/adapters/responses/streaming.ts +344 -0
  178. package/wire/assets/openllm-light.svg +18 -0
  179. package/wire/assets/openllm.svg +18 -0
  180. package/wire/features/account-rank.ts +166 -0
  181. package/wire/features/compaction/compact-request.ts +862 -0
  182. package/wire/features/compaction/compaction-text.ts +43 -0
  183. package/wire/features/context-demote.ts +47 -0
  184. package/wire/features/context-overflow-strategy.ts +26 -0
  185. package/wire/features/context-skip.ts +170 -0
  186. package/wire/features/conversation-affinity.ts +144 -0
  187. package/wire/features/max-tokens-backfill.ts +141 -0
  188. package/wire/features/model-caps.ts +53 -0
  189. package/wire/features/model-settings.ts +24 -0
  190. package/wire/features/output-limit-clamp.ts +64 -0
  191. package/wire/features/quota-gate.ts +85 -0
  192. package/wire/index.ts +44 -0
  193. package/wire/lib/attempt-outcome.ts +43 -0
  194. package/wire/lib/canonical/content-part.ts +38 -0
  195. package/wire/lib/canonical/count-tokens-capability.ts +138 -0
  196. package/wire/lib/canonical/encoding-select.ts +82 -0
  197. package/wire/lib/canonical/image-signature.ts +202 -0
  198. package/wire/lib/canonical/image-sse.ts +216 -0
  199. package/wire/lib/canonical/message.ts +43 -0
  200. package/wire/lib/canonical/token-estimate.ts +266 -0
  201. package/wire/lib/encrypted-content.ts +66 -0
  202. package/wire/lib/error-class.ts +154 -0
  203. package/wire/lib/error-envelope.ts +56 -0
  204. package/wire/lib/forwarded-headers.ts +180 -0
  205. package/wire/lib/provider-error-rules.ts +48 -0
  206. package/wire/lib/refusal.ts +38 -0
  207. package/wire/lib/responses-apply-patch.ts +104 -0
  208. package/wire/lib/responses-namespace.ts +53 -0
  209. package/wire/lib/secret-scrub.ts +101 -0
  210. package/wire/lib/streaming/accumulate.ts +221 -0
  211. package/wire/lib/streaming/finish-reason.ts +33 -0
  212. package/wire/lib/streaming/peek.ts +154 -0
  213. package/wire/lib/streaming/provider-decode.ts +259 -0
  214. package/wire/lib/streaming/response-stream.ts +71 -0
  215. package/wire/lib/streaming/sse.ts +699 -0
  216. package/wire/lib/streaming/strip-tool-calls.ts +95 -0
  217. package/wire/lib/streaming/upstream-error.ts +58 -0
  218. package/wire/lib/strip-subagent-isolation.ts +284 -0
  219. package/wire/lib/thinking-signature.ts +156 -0
  220. package/wire/lib/token-ruler/bpe-core.ts +426 -0
  221. package/wire/lib/token-ruler/index.ts +2 -0
  222. package/wire/lib/token-ruler/ruler.ts +79 -0
  223. package/wire/lib/token-ruler/vocab/claude-ranks.ts +16 -0
  224. package/wire/lib/token-ruler/vocab/claude.ts +22 -0
  225. package/wire/lib/token-ruler/vocab/o200k-ranks.ts +18 -0
  226. package/wire/lib/token-ruler/vocab/o200k.ts +19 -0
  227. package/wire/lib/tool-name-map.ts +271 -0
  228. package/wire/lib/tool-schema.ts +353 -0
  229. package/wire/lib/usage-observer.ts +125 -0
  230. package/wire/providers/anthropic/adaptive-thinking.ts +291 -0
  231. package/wire/providers/anthropic/beta-headers.ts +165 -0
  232. package/wire/providers/anthropic/index.ts +10 -0
  233. package/wire/providers/anthropic/request.ts +607 -0
  234. package/wire/providers/anthropic/response.ts +155 -0
  235. package/wire/providers/anthropic/streaming.ts +315 -0
  236. package/wire/providers/anthropic/web-search-domains.ts +49 -0
  237. package/wire/providers/chatgpt/common.ts +136 -0
  238. package/wire/providers/chatgpt/index.ts +9 -0
  239. package/wire/providers/chatgpt/request.ts +959 -0
  240. package/wire/providers/chatgpt/streaming.ts +1007 -0
  241. package/wire/providers/chatgpt/web-search.ts +63 -0
  242. package/wire/providers/grok/web-search.ts +87 -0
  243. package/wire/providers/kimi/web-search.ts +145 -0
  244. package/wire/providers/upstream-deny.ts +355 -0
  245. package/wire/providers/upstream-request.ts +619 -0
@@ -0,0 +1,354 @@
1
+ import { Effect, Schema as S } from "effect";
2
+ import { PROVIDER_TIER_METHODOLOGY_VERSION } from "./provider-tier";
3
+
4
+ /**
5
+ * Public usage index — OpenLLM's own aggregate projection of gateway activity,
6
+ * published as exact figures. This is our analytics, not a re-release of any
7
+ * upstream vendor's data: raw counts, projected per-tier value, and period-over-
8
+ * period change, with no suppression, bucketing, floors, or noise. Rows are
9
+ * recomputed and OVERWRITTEN each rollup run (live, never frozen).
10
+ */
11
+
12
+ /**
13
+ * Explicit value-methodology id on the public response. Same string as
14
+ * {@link PROVIDER_TIER_METHODOLOGY_VERSION} / public value `metric_version`.
15
+ * Cross-deployment merge MUST compare this literally — never default a peer
16
+ * that omits it to the local current version.
17
+ */
18
+ export const PUBLIC_USAGE_VALUE_METHODOLOGY_VERSION =
19
+ PROVIDER_TIER_METHODOLOGY_VERSION;
20
+
21
+ export const PublicUsageMetric = S.Literals([
22
+ "model_popularity",
23
+ "provider_popularity",
24
+ "value",
25
+ ]);
26
+ export type TPublicUsageMetric = S.Schema.Type<typeof PublicUsageMetric>;
27
+
28
+ export const PublicUsagePopularityMetrics = S.Struct({
29
+ users: S.Number,
30
+ user_days: S.Number,
31
+ requests: S.Number,
32
+ prev_users: S.NullOr(S.Number),
33
+ });
34
+ export type TPublicUsagePopularityMetrics = S.Schema.Type<
35
+ typeof PublicUsagePopularityMetrics
36
+ >;
37
+
38
+ export const PublicUsageValueMetrics = S.Struct({
39
+ value_usd_30d: S.Number,
40
+ accounts: S.Number,
41
+ /** Valid meter-delta pairs supporting the selected value estimate. */
42
+ pair_count: S.Number,
43
+ /** Ratio clustering quality for the selected value estimate. */
44
+ tightness: S.Number,
45
+ prev_value_usd_30d: S.NullOr(S.Number),
46
+ });
47
+ export type TPublicUsageValueMetrics = S.Schema.Type<
48
+ typeof PublicUsageValueMetrics
49
+ >;
50
+
51
+ /** The exact figures stored per non-marker rollup row in `metrics` jsonb. */
52
+ export const PublicUsageIndexMetrics = S.Union([
53
+ PublicUsagePopularityMetrics,
54
+ PublicUsageValueMetrics,
55
+ ]);
56
+ export type TPublicUsageIndexMetrics = S.Schema.Type<
57
+ typeof PublicUsageIndexMetrics
58
+ >;
59
+
60
+ /** Metadata marker that represents an otherwise empty completed bucket. */
61
+ export const PUBLIC_USAGE_INDEX_BUCKET_MARKER = "__bucket__";
62
+
63
+ /**
64
+ * Internal payload used only by the `__bucket__` completion marker. The value
65
+ * bucket's marker carries a fingerprint of the eligible (provider, account,
66
+ * tier) set it was derived from, so a reader can distinguish changed inputs
67
+ * against mere elapsed time and refresh the bucket in place. Optional: markers
68
+ * written before the field existed (and popularity markers) omit it.
69
+ */
70
+ export const PublicUsageIndexMarkerMetrics = S.Struct({
71
+ tier_set_fingerprint: S.optional(S.String),
72
+ evidence_stamp: S.optional(S.String),
73
+ });
74
+ export type TPublicUsageIndexMarkerMetrics = S.Schema.Type<
75
+ typeof PublicUsageIndexMarkerMetrics
76
+ >;
77
+
78
+ /**
79
+ * The metric-specific portion of a stored row. This makes a row's sibling
80
+ * `metric` column the discriminator for its otherwise unrelated JSON payload.
81
+ */
82
+ export const PublicUsageIndexStoredMetric = S.Union([
83
+ S.Struct({
84
+ metric: S.Literals(["model_popularity"]),
85
+ subject: S.String,
86
+ metrics: PublicUsagePopularityMetrics,
87
+ }),
88
+ S.Struct({
89
+ metric: S.Literals(["provider_popularity"]),
90
+ subject: S.String,
91
+ metrics: PublicUsagePopularityMetrics,
92
+ }),
93
+ S.Struct({
94
+ metric: S.Literals(["value"]),
95
+ subject: S.String,
96
+ metrics: PublicUsageValueMetrics,
97
+ }),
98
+ S.Struct({
99
+ metric: PublicUsageMetric,
100
+ subject: S.Literals([PUBLIC_USAGE_INDEX_BUCKET_MARKER]),
101
+ metrics: PublicUsageIndexMarkerMetrics,
102
+ }),
103
+ ]);
104
+ export type TPublicUsageIndexStoredMetric = S.Schema.Type<
105
+ typeof PublicUsageIndexStoredMetric
106
+ >;
107
+
108
+ const PublicUsageIndexRowBase = S.Struct({
109
+ metric_version: S.String,
110
+ provider: S.String,
111
+ label: S.String,
112
+ period_start: S.String,
113
+ period_end: S.String,
114
+ updated_at: S.String,
115
+ });
116
+
117
+ /** One rollup row, matching the `public_usage_index` table. */
118
+ export const PublicUsageIndexRow = S.Union([
119
+ S.Struct({
120
+ ...PublicUsageIndexRowBase.fields,
121
+ metric: S.Literals(["model_popularity"]),
122
+ subject: S.String,
123
+ metrics: PublicUsagePopularityMetrics,
124
+ }),
125
+ S.Struct({
126
+ ...PublicUsageIndexRowBase.fields,
127
+ metric: S.Literals(["provider_popularity"]),
128
+ subject: S.String,
129
+ metrics: PublicUsagePopularityMetrics,
130
+ }),
131
+ S.Struct({
132
+ ...PublicUsageIndexRowBase.fields,
133
+ metric: S.Literals(["value"]),
134
+ subject: S.String,
135
+ metrics: PublicUsageValueMetrics,
136
+ }),
137
+ S.Struct({
138
+ ...PublicUsageIndexRowBase.fields,
139
+ metric: PublicUsageMetric,
140
+ subject: S.Literals([PUBLIC_USAGE_INDEX_BUCKET_MARKER]),
141
+ metrics: PublicUsageIndexMarkerMetrics,
142
+ }),
143
+ ]);
144
+ export type TPublicUsageIndexRow = S.Schema.Type<typeof PublicUsageIndexRow>;
145
+
146
+ /** Factual caption describing what the figures measure (not a legal hedge). */
147
+ export const PUBLIC_USAGE_INDEX_CAPTION =
148
+ "Trends measured across OpenLLM gateway activity";
149
+
150
+ export const PublicModelPopularity = S.Struct({
151
+ /** The provider's registry `displayName` — a rendered label, not a key. */
152
+ provider: S.String,
153
+ /**
154
+ * The stable provider slug (`claude_code`, `openai`, …) behind that label.
155
+ * Same role as `PublicValueByTier.provider_slug`: anything rendering a logo,
156
+ * a tint or a public brand name keys off THIS, since `provider` above is a
157
+ * display string. Empty only for a legacy label the registry no longer knows.
158
+ *
159
+ * Decoded with a default — see the note on cross-deployment merging below.
160
+ */
161
+ provider_slug: S.String.pipe(
162
+ S.optional,
163
+ S.withDecodingDefault(Effect.succeed("")),
164
+ ),
165
+ model: S.String,
166
+ users: S.Number,
167
+ user_days: S.Number,
168
+ requests: S.Number,
169
+ /**
170
+ * Percent change in distinct users vs the previous window; null when there
171
+ * is no prior period, or when the prior is too small to divide by — see
172
+ * `is_new` for the third state and the reader's floors for the threshold.
173
+ */
174
+ pct_change: S.NullOr(S.Number),
175
+ /**
176
+ * The row arrived this period: it carries real activity now and the prior
177
+ * window had none worth comparing against. Only ever true while
178
+ * `pct_change` is null — the two together are a tri-state, since a percent
179
+ * off a negligible base is a number, not a measurement.
180
+ *
181
+ * Decoded with a default — see the note on cross-deployment merging below.
182
+ */
183
+ is_new: S.Boolean.pipe(
184
+ S.optional,
185
+ S.withDecodingDefault(Effect.succeed(false)),
186
+ ),
187
+ });
188
+ export type TPublicModelPopularity = S.Schema.Type<
189
+ typeof PublicModelPopularity
190
+ >;
191
+
192
+ export const PublicProviderPopularity = S.Struct({
193
+ /** The provider's registry `displayName` — a rendered label, not a key. */
194
+ provider: S.String,
195
+ /**
196
+ * The stable provider slug (`claude_code`, `openai`, …) behind that label.
197
+ * Unlike the model rows, a provider row already stores the slug as its
198
+ * SUBJECT, so this is carried straight through rather than recovered from
199
+ * the registry. Anything rendering a logo, a tint or a public brand name
200
+ * keys off THIS, since `provider` above is a display string.
201
+ *
202
+ * Decoded with a default — see the note on cross-deployment merging below.
203
+ */
204
+ provider_slug: S.String.pipe(
205
+ S.optional,
206
+ S.withDecodingDefault(Effect.succeed("")),
207
+ ),
208
+ users: S.Number,
209
+ user_days: S.Number,
210
+ requests: S.Number,
211
+ pct_change: S.NullOr(S.Number),
212
+ /** See `PublicModelPopularity.is_new`. */
213
+ is_new: S.Boolean.pipe(
214
+ S.optional,
215
+ S.withDecodingDefault(Effect.succeed(false)),
216
+ ),
217
+ });
218
+ export type TPublicProviderPopularity = S.Schema.Type<
219
+ typeof PublicProviderPopularity
220
+ >;
221
+
222
+ /**
223
+ * One period's reading for a tier, for the value trend series.
224
+ *
225
+ * Deliberately only the two fields a line needs. The calibration figures
226
+ * (`accounts`, `pair_count`, `tightness`) describe how well a SINGLE estimate
227
+ * is supported and are published on the current reading; repeating them for
228
+ * every historical point would multiply the payload by the number of retained
229
+ * buckets to say something no line can draw.
230
+ */
231
+ export const PublicValuePoint = S.Struct({
232
+ /** ISO period end, and the x value of the point. */
233
+ period_end: S.String,
234
+ value_usd_30d: S.Number,
235
+ });
236
+ export type TPublicValuePoint = S.Schema.Type<typeof PublicValuePoint>;
237
+
238
+ /**
239
+ * A field added to the public response AFTER deployments began reading each
240
+ * other's copies.
241
+ *
242
+ * `mergeConfiguredPublicUsageIndex` fetches a PEER deployment's
243
+ * `/api/public/usage-index` and decodes it with this schema, so a field that
244
+ * is merely required would make every merge fail — a permitted local fallback
245
+ * that is not cacheable — for the whole window in which the two deployments
246
+ * disagree. Decoded with a default instead: the property stays non-optional
247
+ * for consumers, and an older peer still parses.
248
+ */
249
+ export const PublicValueByTier = S.Struct({
250
+ /**
251
+ * The provider's registry `displayName` — a sign-in-flow label ("Claude
252
+ * (Pro/Max sign-in)"), kept for callers that already read it.
253
+ */
254
+ provider: S.String,
255
+ /**
256
+ * The stable provider slug (`claude_code`, `chatgpt`, …), split off the
257
+ * row's `provider:tier` subject. `provider` above is a display string and so
258
+ * cannot key a brand map; anything rendering a logo, a tint or a public
259
+ * brand name keys off THIS.
260
+ *
261
+ * Decoded with a default — see the note on cross-deployment merging below.
262
+ */
263
+ provider_slug: S.String.pipe(
264
+ S.optional,
265
+ S.withDecodingDefault(Effect.succeed("")),
266
+ ),
267
+ tier: S.String,
268
+ /** Projected API-equivalent value of the best-calibrated subscription per 30 days. */
269
+ value_usd_30d: S.Number,
270
+ /** Eligible calibrated accounts in the tier; the figure is the best-calibrated one of them. */
271
+ accounts: S.Number,
272
+ /** Valid meter-delta pairs supporting the selected account's estimate. */
273
+ pair_count: S.Number,
274
+ /** Ratio clustering quality for the selected account's estimate. */
275
+ tightness: S.Number,
276
+ /**
277
+ * Percent change vs the previous window; null when there is no prior, or
278
+ * when the prior is a negligible fraction of the period's leading tier. A
279
+ * tier worth a few dollars swings by thousands of percent on one account's
280
+ * ordinary week, which says nothing about the tier and crowds out the
281
+ * figures that do. See `is_new` for the third state.
282
+ */
283
+ pct_change: S.NullOr(S.Number),
284
+ /** See `PublicModelPopularity.is_new`. */
285
+ is_new: S.Boolean.pipe(
286
+ S.optional,
287
+ S.withDecodingDefault(Effect.succeed(false)),
288
+ ),
289
+ /**
290
+ * Every retained period for this tier, oldest first, INCLUDING the current
291
+ * one — so a consumer plots `history` alone rather than stitching it to the
292
+ * top-level reading and risking a duplicated or missing final point.
293
+ *
294
+ * The buckets were always kept (`public_usage_index` is keyed on
295
+ * `(metric_version, metric, subject, period_start)`); it was the reader that
296
+ * dropped them. A tier measured for the first time has a single point, which
297
+ * is a fact a chart has to render rather than an error.
298
+ */
299
+ history: S.Array(PublicValuePoint).pipe(
300
+ S.optional,
301
+ S.withDecodingDefault(Effect.succeed([])),
302
+ ),
303
+ });
304
+ export type TPublicValueByTier = S.Schema.Type<typeof PublicValueByTier>;
305
+
306
+ export const PeriodWindow = S.Struct({
307
+ period_start: S.NullOr(S.String),
308
+ period_end: S.NullOr(S.String),
309
+ });
310
+ export type TPeriodWindow = S.Schema.Type<typeof PeriodWindow>;
311
+
312
+ /**
313
+ * Public usage artifact: exact aggregate figures grouped for display. The
314
+ * top-level period is the min/max envelope across metric-specific windows,
315
+ * retained for backward compatibility.
316
+ *
317
+ * `value_methodology_version` identifies the recurring-value economics behind
318
+ * `value_by_tier`. Unlike fields decoded with defaults for mixed-version peers,
319
+ * this one is required on every response we emit, and a configured mandatory
320
+ * merge rejects a peer that omits it or reports a different string — never
321
+ * assume an old peer shares the local methodology, and never fall back to
322
+ * local-only value figures when the merge URL is set.
323
+ */
324
+ export const PublicUsageIndexResponse = S.Struct({
325
+ period_start: S.NullOr(S.String),
326
+ period_end: S.NullOr(S.String),
327
+ windows: S.Struct({
328
+ model: PeriodWindow,
329
+ provider: PeriodWindow,
330
+ value: PeriodWindow,
331
+ }),
332
+ caption: S.Literals([PUBLIC_USAGE_INDEX_CAPTION]),
333
+ /**
334
+ * Shared with {@link PUBLIC_USAGE_VALUE_METHODOLOGY_VERSION}. Emit the
335
+ * constant; merge compares it literally before combining `value_by_tier`.
336
+ */
337
+ value_methodology_version: S.String,
338
+ model_popularity: S.Array(PublicModelPopularity),
339
+ provider_popularity: S.Array(PublicProviderPopularity),
340
+ value_by_tier: S.Array(PublicValueByTier),
341
+ });
342
+ export type TPublicUsageIndexResponse = S.Schema.Type<
343
+ typeof PublicUsageIndexResponse
344
+ >;
345
+
346
+ export function hasPublicUsageIndexData(
347
+ response: TPublicUsageIndexResponse,
348
+ ): boolean {
349
+ return (
350
+ response.model_popularity.length > 0 ||
351
+ response.provider_popularity.length > 0 ||
352
+ response.value_by_tier.length > 0
353
+ );
354
+ }
@@ -0,0 +1,31 @@
1
+ /**
2
+ * GENERATED FILE — do not edit by hand.
3
+ *
4
+ * Source of truth: the static model catalog's rows carrying
5
+ * `capabilities: ["realtime"]` (`packages/api/catalog/models/*`).
6
+ * Regenerate with:
7
+ *
8
+ * bun run build:realtime-generated
9
+ *
10
+ * `scripts/check-realtime-generated.ts` (`bun run check:realtime-generated`)
11
+ * fails when this artifact drifts from the catalog.
12
+ *
13
+ * WHY THIS IS GENERATED RATHER THAN LOOKED UP — the documented exception:
14
+ * the realtime model id is decoded by the SHIPPED daemon binary at mux
15
+ * admission (`RealtimeStreamOpenPayload`), so it must be a literal owned by
16
+ * `protocol`. `protocol` cannot import `packages/api` (layering), and a
17
+ * runtime catalog read would add a daemon -> API dependency at admission time
18
+ * and break decode compatibility with deployed binaries. Generating keeps the
19
+ * catalog as the ONE source while leaving the wire literal static.
20
+ *
21
+ * This artifact carries ids only — never catalog metadata — and asserts
22
+ * nothing about availability.
23
+ */
24
+
25
+ /** Every realtime `provider_model_id` the catalog declares. */
26
+ export const REALTIME_MODEL_IDS = ["grok-voice-latest"] as const;
27
+
28
+ /** The id each realtime provider dials by default. */
29
+ export const REALTIME_DEFAULT_MODEL_BY_PROVIDER = {
30
+ grok: "grok-voice-latest",
31
+ } as const;