@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,59 @@
1
+ import { Schema as S } from "effect";
2
+ import type { TMediaDefaultSurface } from "./media-default";
3
+ import { MediaDefaultSurface } from "./media-default";
4
+
5
+ /**
6
+ * The surface an EXPLICIT-model plan fetch is for.
7
+ *
8
+ * `GET /api/daemon/plan?model=…` was surface-blind: the daemon asked for
9
+ * whatever model string the client sent, whichever endpoint it arrived on,
10
+ * and the cloud resolved it under the `chat` default. For an unambiguous
11
+ * media id that merely failed to resolve; for an AMBIGUOUS family name it
12
+ * resolved to the wrong thing entirely — `model=grok` on
13
+ * `/v1/images/generations` planned the grok CHAT model, while the cloud's
14
+ * own image handler (which knows its surface) selects grok's image model
15
+ * for the identical request. One request, two answers, decided by which
16
+ * transport happened to serve it.
17
+ *
18
+ * So the surface travels WITH the query. It is the surface NAME, not a
19
+ * capability: the mapping from surface to capability (`image_edit` →
20
+ * `image_editing`, never `image_generation`) already exists once on the
21
+ * cloud, next to the gate that enforces it, and must not be re-stated by
22
+ * every caller.
23
+ *
24
+ * Absent means "no surface stated" and keeps the historical chat-default
25
+ * behaviour — an older compiled daemon never sends it, and a plan it
26
+ * fetches must keep working exactly as before.
27
+ */
28
+ export const PLAN_SURFACE_QUERY_KEY = "surface";
29
+
30
+ /** A surface a plan can be scoped to — the media-default surface set. */
31
+ export const PlanSurface = MediaDefaultSurface;
32
+ export type TPlanSurface = TMediaDefaultSurface;
33
+
34
+ const decodeSurface = S.decodeUnknownResult(PlanSurface);
35
+
36
+ export const encodePlanSurfaceQueryValue = (surface: TPlanSurface): string =>
37
+ surface;
38
+
39
+ /**
40
+ * `absent` (no surface stated) and `invalid` (stated, unrecognised) are
41
+ * deliberately different results: the first must keep the legacy default,
42
+ * the second is our own client sending something wrong and is worth a 400
43
+ * rather than being silently planned on the wrong surface.
44
+ */
45
+ export type TPlanSurfaceQuery =
46
+ | { readonly kind: "absent" }
47
+ | { readonly kind: "surface"; readonly surface: TPlanSurface }
48
+ | { readonly kind: "invalid" };
49
+
50
+ export const decodePlanSurfaceQuery = (
51
+ params: URLSearchParams,
52
+ ): TPlanSurfaceQuery => {
53
+ const raw = params.get(PLAN_SURFACE_QUERY_KEY);
54
+ if (raw === null || raw.length === 0) return { kind: "absent" };
55
+ const decoded = decodeSurface(raw);
56
+ return decoded._tag === "Success"
57
+ ? { kind: "surface", surface: decoded.success }
58
+ : { kind: "invalid" };
59
+ };
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Providers whose live catalogs are large enough that the user picks which
3
+ * of their models are LISTED (`config.extra.provider_models`). Selection is
4
+ * a listing filter only: an explicit request for an unselected id still
5
+ * resolves and routes. Declared once here so api and dashboard agree.
6
+ */
7
+ export const MODEL_SELECTABLE_PROVIDERS: ReadonlySet<string> = new Set([
8
+ "openrouter",
9
+ "nvidia",
10
+ "cloudflare",
11
+ "ollama_cloud",
12
+ "opencode_zen",
13
+ ]);
14
+
15
+ export const isModelSelectableProvider = (provider: string): boolean =>
16
+ MODEL_SELECTABLE_PROVIDERS.has(provider);
@@ -0,0 +1,206 @@
1
+ import { Schema as S } from "effect";
2
+
3
+ /** Immutable `detail` sentinel for an indeterminate daemon status probe. */
4
+ export const STATUS_CHECK_FAILED_DETAIL = "status check failed";
5
+
6
+ /**
7
+ * Typed observation of a subscription provider. Optional on the wire so old
8
+ * daemons and persisted blobs remain valid; consumers must run
9
+ * {@link normalizeProviderConnection} rather than reading `status` alone.
10
+ */
11
+ export const DaemonProviderObservation = S.Literals([
12
+ "connected",
13
+ "signed_out",
14
+ "disconnected",
15
+ "unknown",
16
+ ]);
17
+ export type TDaemonProviderObservation = S.Schema.Type<
18
+ typeof DaemonProviderObservation
19
+ >;
20
+
21
+ export const DaemonProviderReasonCode = S.Literals([
22
+ "probe_timeout",
23
+ "probe_failed",
24
+ "keychain_unavailable",
25
+ "store_unreadable",
26
+ "cli_unavailable",
27
+ /** Host CLI is a shebang script whose interpreter is missing on the spawn PATH. */
28
+ "cli_runtime_missing",
29
+ "credential_absent",
30
+ ]);
31
+ export type TDaemonProviderReasonCode = S.Schema.Type<
32
+ typeof DaemonProviderReasonCode
33
+ >;
34
+
35
+ export type TDaemonProviderObservationResult = {
36
+ readonly observation: TDaemonProviderObservation;
37
+ readonly reason_code?: TDaemonProviderReasonCode;
38
+ };
39
+
40
+ /**
41
+ * Why an `auth` hop cooldown was armed from a native refresh, not a vendor
42
+ * 401. Distinct from {@link DaemonProviderReasonCode} so it never rewrites
43
+ * `status` / `observation`.
44
+ */
45
+ export const AuthRefreshCooldownReason = S.Literals([
46
+ "refresh_abandoned",
47
+ "refresh_failed",
48
+ ]);
49
+ export type TAuthRefreshCooldownReason = S.Schema.Type<
50
+ typeof AuthRefreshCooldownReason
51
+ >;
52
+
53
+ /**
54
+ * Visibility-only: a live local hop cooldown with reason `auth` for this
55
+ * provider. Does not change `status` / `observation` / the connection
56
+ * `reason_code`. Optional `reason_code` here is the refresh-local cause.
57
+ */
58
+ export const DaemonProviderUpstreamAuthCooldown = S.Struct({
59
+ until_ms: S.Number,
60
+ model_id: S.String,
61
+ reason_code: S.optional(AuthRefreshCooldownReason),
62
+ });
63
+ export type TDaemonProviderUpstreamAuthCooldown = S.Schema.Type<
64
+ typeof DaemonProviderUpstreamAuthCooldown
65
+ >;
66
+
67
+ const OBSERVATIONS = new Set<string>(DaemonProviderObservation.literals);
68
+ const REASONS = new Set<string>(DaemonProviderReasonCode.literals);
69
+
70
+ export type TNormalizedProviderConnection = {
71
+ readonly observation: TDaemonProviderObservation;
72
+ readonly reason_code: TDaemonProviderReasonCode | undefined;
73
+ readonly pending: boolean;
74
+ readonly signed_out: boolean;
75
+ /** Proven currently-session connected with no in-flight login. */
76
+ readonly serviceable: boolean;
77
+ };
78
+
79
+ export type TProviderConnectionInput = {
80
+ readonly status?: unknown;
81
+ readonly connected?: unknown;
82
+ readonly observation?: unknown;
83
+ readonly reason_code?: unknown;
84
+ readonly pending_auth?: unknown;
85
+ readonly cli_installed?: unknown;
86
+ readonly detail?: unknown;
87
+ };
88
+
89
+ const isPendingAuth = (value: unknown): boolean => {
90
+ if (value === null || value === undefined) return false;
91
+ return typeof value === "object";
92
+ };
93
+
94
+ const inferReason = (
95
+ conn: TProviderConnectionInput,
96
+ ): TDaemonProviderReasonCode | undefined => {
97
+ if (typeof conn.reason_code === "string" && REASONS.has(conn.reason_code)) {
98
+ return conn.reason_code as TDaemonProviderReasonCode;
99
+ }
100
+ const detail =
101
+ typeof conn.detail === "string" ? conn.detail.toLowerCase() : "";
102
+ if (detail.includes("keychain")) return "keychain_unavailable";
103
+ if (
104
+ detail.includes("unreadable") ||
105
+ detail.includes("eacces") ||
106
+ detail.includes("permission denied") ||
107
+ detail.includes("parse")
108
+ ) {
109
+ return "store_unreadable";
110
+ }
111
+ if (
112
+ conn.detail === STATUS_CHECK_FAILED_DETAIL ||
113
+ detail.includes("timeout") ||
114
+ detail.includes("timed out")
115
+ ) {
116
+ return "probe_timeout";
117
+ }
118
+ if (
119
+ detail.includes("runtime") &&
120
+ (detail.includes("missing") || detail.includes("not on the daemon path"))
121
+ ) {
122
+ return "cli_runtime_missing";
123
+ }
124
+ if (detail.includes("not installed") || conn.cli_installed === false) {
125
+ return "cli_unavailable";
126
+ }
127
+ if (
128
+ detail.includes("not signed in") ||
129
+ detail.includes("no stored credential") ||
130
+ (detail.includes("credential") && detail.includes("absent"))
131
+ ) {
132
+ return "credential_absent";
133
+ }
134
+ return undefined;
135
+ };
136
+
137
+ const inferObservation = (
138
+ conn: TProviderConnectionInput,
139
+ pending: boolean,
140
+ signedOut: boolean,
141
+ ): TDaemonProviderObservation => {
142
+ if (signedOut) return "signed_out";
143
+ if (
144
+ typeof conn.observation === "string" &&
145
+ OBSERVATIONS.has(conn.observation)
146
+ ) {
147
+ return conn.observation as TDaemonProviderObservation;
148
+ }
149
+ if (conn.status === "connected") return "connected";
150
+ if (conn.status === "disconnected") {
151
+ const reason = inferReason(conn);
152
+ if (
153
+ reason === "probe_timeout" ||
154
+ reason === "probe_failed" ||
155
+ reason === "keychain_unavailable" ||
156
+ reason === "store_unreadable" ||
157
+ reason === "cli_unavailable" ||
158
+ reason === "cli_runtime_missing"
159
+ ) {
160
+ return "unknown";
161
+ }
162
+ return "disconnected";
163
+ }
164
+ if (conn.connected === true) return "connected";
165
+ if (conn.connected === false) {
166
+ const reason = inferReason(conn);
167
+ if (
168
+ reason === "probe_timeout" ||
169
+ reason === "probe_failed" ||
170
+ reason === "keychain_unavailable" ||
171
+ reason === "store_unreadable" ||
172
+ reason === "cli_unavailable" ||
173
+ reason === "cli_runtime_missing"
174
+ ) {
175
+ return "unknown";
176
+ }
177
+ return "disconnected";
178
+ }
179
+ if (pending) return "unknown";
180
+ return "unknown";
181
+ };
182
+
183
+ /**
184
+ * One canonical projection of a provider connection blob. Typed fields win;
185
+ * legacy `status` / `connected` / `detail` are the compatibility fallback.
186
+ *
187
+ * Precedence: `signed_out` always wins. `pending_auth` is never serviceable.
188
+ * `unknown` never becomes logout and never counts as proven connected.
189
+ */
190
+ export const normalizeProviderConnection = (
191
+ conn: TProviderConnectionInput,
192
+ ): TNormalizedProviderConnection => {
193
+ const pending = isPendingAuth(conn.pending_auth);
194
+ const signedOut =
195
+ conn.status === "signed_out" || conn.observation === "signed_out";
196
+ const observation = inferObservation(conn, pending, signedOut);
197
+ const reason_code = inferReason(conn);
198
+ const serviceable = !signedOut && !pending && observation === "connected";
199
+ return {
200
+ observation: signedOut ? "signed_out" : observation,
201
+ reason_code,
202
+ pending,
203
+ signed_out: signedOut,
204
+ serviceable,
205
+ };
206
+ };
@@ -0,0 +1,67 @@
1
+ /**
2
+ * Shared provider-tier identity. Trim only — never fold case or aliases —
3
+ * so `pro` and `prolite` stay distinct. Missing/blank plan is `null`.
4
+ *
5
+ * `providerTierBucketKey` encodes `(provider, accountHash, plan)` with
6
+ * length-prefixed segments so values containing the delimiter cannot collide.
7
+ * Internal timeline keys may pass `plan: null`. A calibratable cache row must
8
+ * not: callers reject null before using this as a cache key.
9
+ */
10
+
11
+ /**
12
+ * Single source for subscription-index cache rows and public value buckets.
13
+ *
14
+ * - `account-owned-v1` — projected 30-day value from the selected window scaled
15
+ * by the observed reset-to-reset span (could treat a one-off early reset as a
16
+ * recurring shorter cadence).
17
+ * - `account-owned-v2` — same single-window forecast, but scaled by the resolved
18
+ * nominal window duration (stated vendor duration / known label / conservative
19
+ * fallback). One early reset no longer shortens the recurring projection.
20
+ *
21
+ * Historical v1 cache/public rows remain stored; readers treat only the current
22
+ * string as live. No DB rewrite.
23
+ */
24
+ export const PROVIDER_TIER_METHODOLOGY_VERSION = "account-owned-v2";
25
+
26
+ export const normalizeProviderTier = (raw: unknown): string | null => {
27
+ if (typeof raw !== "string") return null;
28
+ const trimmed = raw.trim();
29
+ return trimmed.length > 0 ? trimmed : null;
30
+ };
31
+
32
+ const encodeSegment = (value: string): string => `${value.length}:${value}`;
33
+
34
+ /** ASCII unit separator — explicit code point so the source stays readable. */
35
+ const SEGMENT_SEP = String.fromCharCode(0x1f);
36
+
37
+ /**
38
+ * Collision-safe tuple encoding. Null plan uses a distinct `0` token, not an
39
+ * empty segment (which would collide with a zero-length string, already
40
+ * rejected by {@link normalizeProviderTier}).
41
+ */
42
+ export const providerTierBucketKey = (
43
+ provider: string,
44
+ accountHash: string,
45
+ plan: string | null,
46
+ ): string =>
47
+ `${encodeSegment(provider)}${SEGMENT_SEP}${encodeSegment(accountHash)}${SEGMENT_SEP}${
48
+ plan === null ? "0" : encodeSegment(plan)
49
+ }`;
50
+
51
+ /** Snapshot-series identity: bucket plus window label, same encoding. */
52
+ export const providerTierWindowSeriesKey = (
53
+ provider: string,
54
+ accountHash: string,
55
+ plan: string | null,
56
+ windowLabel: string,
57
+ ): string =>
58
+ `${providerTierBucketKey(provider, accountHash, plan)}${SEGMENT_SEP}${encodeSegment(windowLabel)}`;
59
+
60
+ /** Observation-sample identity for local idempotence of a (tier, as_of) pair. */
61
+ export const providerTierObservationSampleKey = (
62
+ provider: string,
63
+ accountHash: string,
64
+ plan: string | null,
65
+ observedAtMs: number,
66
+ ): string =>
67
+ `${providerTierBucketKey(provider, accountHash, plan)}${SEGMENT_SEP}${encodeSegment(String(observedAtMs))}`;
@@ -0,0 +1,263 @@
1
+ import { Schema as S } from "effect";
2
+
3
+ /**
4
+ * Uniform usage snapshot — THE canonical struct every provider's usage
5
+ * read reduces into, at the daemon delegation boundary.
6
+ *
7
+ * Each OAuth-backed provider reports usage in a wildly different shape,
8
+ * and vendors RESHAPE those payloads without notice (OpenAI has already
9
+ * collapsed Codex's 5h-primary + weekly-secondary pair into a single
10
+ * weekly primary window mid-flight):
11
+ *
12
+ * - Anthropic Pro/Max ("claude_code"): OAuth usage endpoint with
13
+ * `utilization` + `resets_at` per rolling window (5h, 7d, and
14
+ * model-scoped 7d windows).
15
+ * - ChatGPT Codex ("chatgpt"): `backend-api/wham/usage` with
16
+ * `used_percent` + `limit_window_seconds` + `reset_at` windows under
17
+ * `rate_limit`.
18
+ * - Kimi Code: `{ usage, limits[] }` rows; Grok: a monthly quota.
19
+ *
20
+ * Rather than push that variance into the client, each delegate reduces
21
+ * its vendor payload into this ONE discriminated union as early as
22
+ * possible — everything downstream (relay persistence, the calibration
23
+ * estimator, the UI) only ever sees this shape, so a vendor-side change
24
+ * is absorbed entirely inside that provider's reducer.
25
+ */
26
+ /** One quota window — e.g. Claude's 5h + 7d, Codex's weekly. */
27
+ export const ProviderUsageWindow = S.Struct({
28
+ /**
29
+ * Human-readable window label — "5-hour", "7-day", "Sonnet 7-day", etc.
30
+ * Doubles as the window's IDENTITY downstream (the calibration series
31
+ * key), so reducers derive it from the window's DURATION whenever the
32
+ * vendor states one — vendor-positional names ("Primary") survive a
33
+ * reshape with a different meaning; a duration label re-keys instead.
34
+ */
35
+ label: S.String,
36
+ /**
37
+ * Stable machine identity for pool → catalog-meter matching, distinct from
38
+ * the display `label`. Windows that are not metered pools omit it.
39
+ */
40
+ meter_id: S.optional(S.String),
41
+ /** 0–100 used percentage in this window. */
42
+ percent_used: S.Number,
43
+ /** Unix epoch milliseconds when this window resets, when known. */
44
+ reset_at_ms: S.NullOr(S.Number),
45
+ /**
46
+ * Window length in milliseconds, when the vendor states one (e.g.
47
+ * Codex's `limit_window_seconds`, Claude's key-implied 5h/7d). Absent
48
+ * when the vendor only names the window.
49
+ */
50
+ window_ms: S.optional(S.Number),
51
+ });
52
+ export type TProviderUsageWindow = S.Schema.Type<typeof ProviderUsageWindow>;
53
+
54
+ /** Percent-used threshold for `allowed_warning` quota status. */
55
+ export const QUOTA_WARN_PERCENT = 80;
56
+ /** Percent-used threshold for `rejected` quota status. */
57
+ export const QUOTA_REJECT_PERCENT = 100;
58
+
59
+ /**
60
+ * Bounded codes for a failed usage refresh while last-good quota is still
61
+ * served. The only values that may appear on `refresh_failure.reason` —
62
+ * never vendor prose, HTTP bodies, URLs, or exception text.
63
+ */
64
+ export const ProviderUsageRefreshFailureReason = S.Literals([
65
+ "credential_expired",
66
+ "account_changed",
67
+ "rate_limited",
68
+ "authorization_failed",
69
+ "subscription_inactive",
70
+ "fetch_failed",
71
+ ]);
72
+ export type TProviderUsageRefreshFailureReason = S.Schema.Type<
73
+ typeof ProviderUsageRefreshFailureReason
74
+ >;
75
+
76
+ export const ProviderUsageRefreshFailure = S.Struct({
77
+ reason: ProviderUsageRefreshFailureReason,
78
+ /** Unix epoch ms of the failed attempt, when known. */
79
+ at_ms: S.optional(S.Number),
80
+ });
81
+ export type TProviderUsageRefreshFailure = S.Schema.Type<
82
+ typeof ProviderUsageRefreshFailure
83
+ >;
84
+
85
+ /**
86
+ * Map an `unavailable.reason` (wire code or provider sentence) onto a
87
+ * {@link TProviderUsageRefreshFailureReason}. Exact known codes first;
88
+ * otherwise keyword / HTTP-status classification. Returns null for empty
89
+ * or placeholder (`loading`) reasons. Never returns the input string.
90
+ */
91
+ export const classifyUsageRefreshFailureReason = (
92
+ reason: string,
93
+ ): TProviderUsageRefreshFailureReason | null => {
94
+ const trimmed = reason.trim();
95
+ if (trimmed.length === 0 || trimmed === "loading") return null;
96
+ if (S.is(ProviderUsageRefreshFailureReason)(trimmed)) return trimmed;
97
+ const lower = trimmed.toLowerCase();
98
+ if (/\b429\b/.test(trimmed) || /rate[\s-]limit/.test(lower)) {
99
+ return "rate_limited";
100
+ }
101
+ if (
102
+ /\b401\b/.test(trimmed) ||
103
+ /authorization was rejected/.test(lower) ||
104
+ /not signed in/.test(lower)
105
+ ) {
106
+ return "authorization_failed";
107
+ }
108
+ if (
109
+ /\b403\b/.test(trimmed) ||
110
+ /no active/.test(lower) ||
111
+ /isn't available on this plan/.test(lower) ||
112
+ /subscription may be inactive/.test(lower)
113
+ ) {
114
+ return "subscription_inactive";
115
+ }
116
+ return "fetch_failed";
117
+ };
118
+
119
+ /**
120
+ * The structural meter shape the quota gate + pool matcher accept — the
121
+ * `meter_id` identity plus its exact vendor aliases. Structurally satisfied by
122
+ * the schema-derived `TSubscriptionMeter`, kept as a hand-written alias so
123
+ * `wire`/`core` can type a meter arg without importing the catalog schema.
124
+ */
125
+ export type TSubscriptionMeterMatch = {
126
+ readonly meter_id: string;
127
+ readonly aliases?: ReadonlyArray<string>;
128
+ };
129
+
130
+ /**
131
+ * Match a subscription catalog meter to the vendor identity emitted on a
132
+ * display-only usage pool. Aliases are exact vendor identities only.
133
+ */
134
+ export const matchesSubscriptionMeter = (
135
+ meter: TSubscriptionMeterMatch | undefined,
136
+ poolMeterId: string | undefined,
137
+ ): boolean => {
138
+ if (meter === undefined || poolMeterId === undefined) return false;
139
+ if (poolMeterId === meter.meter_id) return true;
140
+ return meter.aliases?.includes(poolMeterId) ?? false;
141
+ };
142
+
143
+ export const ProviderUsageSnapshot = S.Union([
144
+ /**
145
+ * One or more quota windows + an overall status. Claude's
146
+ * shared plan meters (`five_hour` + `seven_day`) and Codex's
147
+ * `rate_limit` windows both flatten into this list. Model-scoped
148
+ * Claude caps (Fable / Opus / Sonnet) and Codex promo pools (Spark)
149
+ * ride on `extra_pools` instead — they meter different usage and
150
+ * must not drive status or the tightest-window face.
151
+ */
152
+ S.Struct({
153
+ kind: S.Literal("quota"),
154
+ status: S.Literals(["allowed", "allowed_warning", "rejected"]),
155
+ /** Optional plan/tier shown alongside the bars. */
156
+ plan: S.optional(S.String),
157
+ /** Tags tier provenance as `official`, `documented-experimental`, or `private-client`. */
158
+ plan_source: S.optional(S.String),
159
+ windows: S.Array(ProviderUsageWindow),
160
+ /** Short human-readable note ("Pro plan — 5h window"). */
161
+ note: S.String,
162
+ /**
163
+ * Unix epoch ms when these figures were last fetched LIVE from the
164
+ * vendor. Stamped by the daemon's usage cache when it serves a cached
165
+ * snapshot; lets the UI show "updated Xm ago". Absent on a fresh read.
166
+ */
167
+ as_of_ms: S.optional(S.Number),
168
+ /**
169
+ * True when these are the LAST KNOWN GOOD figures, served because a
170
+ * live refresh failed (typically the vendor usage endpoint is
171
+ * rate-limited, which is independent of inference). The numbers are
172
+ * still meaningful — just not this-instant — so the UI renders them
173
+ * with a "cached" badge rather than an error. Absent/false on a fresh
174
+ * read. See `packages/cli/daemon/src/usage-cache.ts`.
175
+ */
176
+ stale: S.optional(S.Boolean),
177
+ /**
178
+ * Last live refresh failure while these good figures are still served.
179
+ * Observation time (`as_of_ms`) stays the successful fetch. Cleared on
180
+ * the next usable snapshot. `reason` is a bounded code only.
181
+ */
182
+ refresh_failure: S.optional(ProviderUsageRefreshFailure),
183
+ /**
184
+ * Feature-scoped pools metering DIFFERENT usage than `windows` (e.g.
185
+ * Codex's per-model promo pools under `additional_rate_limits`).
186
+ * DISPLAY-ONLY: the relay persists only `windows` for calibration —
187
+ * a separate pool priced against the main meter's K̂ would be wrong,
188
+ * and pools must never become the card's tightest-window meter.
189
+ */
190
+ extra_pools: S.optional(S.Array(ProviderUsageWindow)),
191
+ /**
192
+ * Vendor credit state, when reported (Codex's `credits` +
193
+ * `rate_limit_reset_credits`). Display-only — lets the card account
194
+ * for capacity that exists OUTSIDE the quota windows.
195
+ */
196
+ credits: S.optional(
197
+ S.Struct({
198
+ /** Raw balance string as the vendor reports it ("0", "1250"). */
199
+ balance: S.String,
200
+ /** Vendor reports the balance as unlimited. */
201
+ unlimited: S.optional(S.Boolean),
202
+ /** Limit-reset credits available (each lifts a hit limit). */
203
+ reset_credits: S.optional(S.Number),
204
+ }),
205
+ ),
206
+ }),
207
+ /**
208
+ * Subscription plan / entitlements snapshot. No live quota number;
209
+ * just "you're on plan X" — for a provider whose usage endpoint
210
+ * exposes no per-window quota.
211
+ */
212
+ S.Struct({
213
+ kind: S.Literal("plan"),
214
+ plan: S.String,
215
+ note: S.String,
216
+ }),
217
+ /**
218
+ * Provider returned an error or doesn't surface anything usable — e.g. not
219
+ * signed in, the stored access token is expired (`reason: "credential_expired"`,
220
+ * no native refresh on this path), the vendor usage endpoint rejected the token,
221
+ * or the plan exposes no quota window the daemon can read. The UI shows
222
+ * `reason`, plus an optional `link` rendered as a button to the provider's own
223
+ * usage / billing page when the figures can only be checked there.
224
+ */
225
+ S.Struct({
226
+ kind: S.Literal("unavailable"),
227
+ reason: S.String,
228
+ link: S.optional(S.String),
229
+ }),
230
+ ]);
231
+ export type TProviderUsageSnapshot = S.Schema.Type<
232
+ typeof ProviderUsageSnapshot
233
+ >;
234
+
235
+ /**
236
+ * Response shape for `GET /api/credentials/{provider}/blob`. Returns
237
+ * the user's OWN ciphertext + nonce so the browser can decrypt
238
+ * locally and forward the plaintext token to the usage endpoint
239
+ * above. Gated on session auth; the caller can only ever fetch
240
+ * blobs they themselves wrote.
241
+ */
242
+ export const CredentialBlobResponse = S.Struct({
243
+ provider: S.String,
244
+ ciphertext: S.String,
245
+ nonce: S.String,
246
+ /** Source stamp used to detect stale team credential-share envelopes. */
247
+ updated_at: S.optional(S.String),
248
+ /** Source vault generation used to detect stale credential-share envelopes. */
249
+ vault_version: S.optional(S.Number),
250
+ });
251
+
252
+ /**
253
+ * Keep team credential-share wrapping independent from rollout order: older
254
+ * blob handlers omit source stamps, and the browser simply avoids stamping
255
+ * rather than inventing one.
256
+ */
257
+ export type TCredentialBlobSourceStamp = {
258
+ readonly updated_at?: string;
259
+ readonly vault_version?: number;
260
+ };
261
+ export type TCredentialBlobResponse = S.Schema.Type<
262
+ typeof CredentialBlobResponse
263
+ >;