@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,345 @@
1
+ import { Schema as S } from "effect";
2
+ import { OpaqueId } from "./doctor-report";
3
+ import { ModelSettingsOverrides } from "./model-settings";
4
+ import { DefaultTier, ExtendedModel } from "./models";
5
+
6
+ /**
7
+ * Wire format a custom-API endpoint speaks. Reuses the same two
8
+ * canonical formats the registry tracks today; the proxy dispatches
9
+ * through `openaiProvider` or `anthropicProvider` accordingly.
10
+ *
11
+ * Used ONLY for the one-shot `/v1/models` discovery probe — the
12
+ * credential blob no longer stores it and the per-user catalog no
13
+ * longer attaches it to entries (wire format is now derived per
14
+ * MODEL via `CustomApiModelKind` below).
15
+ *
16
+ * Defined here (not in `./credentials`) to keep the dependency
17
+ * direction one-way (`credentials.ts` may depend on `./config`).
18
+ */
19
+ export const CustomApiWireFormat = S.Literals(["openai", "anthropic"]);
20
+ export type TCustomApiWireFormat = S.Schema.Type<typeof CustomApiWireFormat>;
21
+
22
+ /**
23
+ * Per-model surface + wire choice. One endpoint can serve a mix of
24
+ * chat / embeddings / image models, and chat models can speak either
25
+ * the OpenAI or the Anthropic wire — packed into one tagged value
26
+ * the dashboard collects via a single per-row select.
27
+ *
28
+ * - `chat_openai` /v1/chat/completions, OpenAI canonical wire
29
+ * - `chat_anthropic` /v1/messages or canonical chat, Anthropic wire
30
+ * - `embeddings` /v1/embeddings, OpenAI wire (the only embeddings
31
+ * surface upstream specs implement)
32
+ * - `image_openai` /v1/images/generations, OpenAI-compatible image
33
+ * gen — what aggregating gateways (LiteLLM,
34
+ * openllm itself, OpenRouter, …) expose,
35
+ * regardless of the underlying model.
36
+ *
37
+ * Native Google AI Studio (`generateContent`) is intentionally
38
+ * absent: its model list is at `/v1beta/models` with a different
39
+ * envelope shape than the OpenAI-style `/v1/models` our discovery
40
+ * probe expects, so it cannot be reached via the discover-then-pick
41
+ * flow. Use the built-in `google/*` catalog entries on the API-keys
42
+ * tab when you want direct Google AI Studio access.
43
+ */
44
+ export const CustomApiModelKind = S.Literals([
45
+ "chat_openai",
46
+ "chat_anthropic",
47
+ "embeddings",
48
+ "image_openai",
49
+ ]);
50
+ export type TCustomApiModelKind = S.Schema.Type<typeof CustomApiModelKind>;
51
+
52
+ export const FallbackGroup = S.Struct({
53
+ name: S.String,
54
+ models: S.Array(S.String),
55
+ });
56
+ export type TFallbackGroup = S.Schema.Type<typeof FallbackGroup>;
57
+
58
+ /** LiteLLM-style `[trigger, alternateModels]` rows (`*` = default alternates). */
59
+ export const ModelFallbackBinding = S.Tuple([S.String, S.Array(S.String)]);
60
+ export type TModelFallbackBinding = S.Schema.Type<typeof ModelFallbackBinding>;
61
+
62
+ /**
63
+ * The dashboard's `/v1/models` probe returns upstream ids plus any reported
64
+ * token limits. The user picks which rows to enable and assigns a `kind`; we
65
+ * deliberately do not auto-include a gateway's entire catalogue.
66
+ */
67
+ /** Canonical input/output limits reported by compatible model lists. */
68
+ export const CustomApiModelLimits = S.Struct({
69
+ /** Prompt/context budget, normalized from any upstream alias. */
70
+ max_input_tokens: S.optional(S.Number),
71
+ /** Completion ceiling when the upstream reports one. */
72
+ max_output_tokens: S.optional(S.Number),
73
+ });
74
+
75
+ /** One model returned by the transient custom-endpoint discovery probe. */
76
+ export const CustomApiDiscoveredModel = S.Struct({
77
+ id: S.String,
78
+ ...CustomApiModelLimits.fields,
79
+ });
80
+ export type TCustomApiDiscoveredModel = S.Schema.Type<
81
+ typeof CustomApiDiscoveredModel
82
+ >;
83
+
84
+ export const CustomApiCatalogModel = S.Struct({
85
+ id: S.String,
86
+ kind: CustomApiModelKind,
87
+ ...CustomApiModelLimits.fields,
88
+ });
89
+ export type TCustomApiCatalogModel = S.Schema.Type<
90
+ typeof CustomApiCatalogModel
91
+ >;
92
+
93
+ /**
94
+ * Per-user catalog entry for a custom OpenAI/Anthropic-compatible
95
+ * endpoint the user has registered on the `/providers` page. The
96
+ * SECRET half (base URL + api key) lives encrypted in
97
+ * `public.credentials` under provider slug `custom:<name>` — only
98
+ * the opt-in model list (id, kind, and discovered token limits) is stored here
99
+ * so the dashboard can populate fallback dropdowns without unlocking the vault.
100
+ */
101
+ export const CustomApiCatalogEntry = S.Struct({
102
+ name: S.String,
103
+ models: S.Array(CustomApiCatalogModel),
104
+ });
105
+ export type TCustomApiCatalogEntry = S.Schema.Type<
106
+ typeof CustomApiCatalogEntry
107
+ >;
108
+
109
+ /**
110
+ * One subscription the user has told us they pay for. `plan` is a plan id
111
+ * from the app's per-provider plan catalog, or `custom` — the escape hatch
112
+ * for regional pricing / seats / a plan we don't list, where `monthly_usd`
113
+ * carries the amount the user typed.
114
+ */
115
+ export const SubscriptionPlanSelection = S.Struct({
116
+ provider: S.String,
117
+ plan: S.String,
118
+ monthly_usd: S.optional(S.Number),
119
+ });
120
+ export type TSubscriptionPlanSelection = S.Schema.Type<
121
+ typeof SubscriptionPlanSelection
122
+ >;
123
+
124
+ export const ContextOverflowStrategy = S.Literals([
125
+ "hop_to_larger_context",
126
+ "compact_in_place",
127
+ ]);
128
+ export type TContextOverflowStrategy = S.Schema.Type<
129
+ typeof ContextOverflowStrategy
130
+ >;
131
+
132
+ /** The thresholds a usage alert can be set to, in percent of the budget. */
133
+ export const UsageAlertThresholdPct = S.Literals([50, 80, 90]);
134
+ export type TUsageAlertThresholdPct = S.Schema.Type<
135
+ typeof UsageAlertThresholdPct
136
+ >;
137
+ export const USAGE_ALERT_DEFAULT_THRESHOLD_PCT: TUsageAlertThresholdPct = 80;
138
+
139
+ export const ExtraConfig = S.Struct({
140
+ model_settings: S.optional(ModelSettingsOverrides),
141
+ search_provider: S.optional(S.String),
142
+ context_overflow_strategy: S.optional(ContextOverflowStrategy),
143
+ custom_apis: S.optional(S.Array(CustomApiCatalogEntry)),
144
+ notification_prefs: S.optional(
145
+ S.Struct({
146
+ auth_loss_email: S.optional(S.Boolean),
147
+ quota_email: S.optional(S.Boolean),
148
+ daemon_idle_email: S.optional(S.Boolean),
149
+ /** Onboarding tips and Pro trial nudges (lifecycle cron). */
150
+ lifecycle_email: S.optional(S.Boolean),
151
+ /**
152
+ * Free-plan usage alerts: one mail at `usage_alert_threshold_pct` of the
153
+ * monthly token budget and one when it is spent.
154
+ */
155
+ usage_alert_email: S.optional(S.Boolean),
156
+ /** One mail three days before a key, device or app connection's
157
+ * access expires (`policy.expires_at`). */
158
+ key_expiry_email: S.optional(S.Boolean),
159
+ }),
160
+ ),
161
+ /** Percent of the Free plan's monthly tokens that triggers the first usage
162
+ * alert. Absent = {@link USAGE_ALERT_DEFAULT_THRESHOLD_PCT}. */
163
+ usage_alert_threshold_pct: S.optional(UsageAlertThresholdPct),
164
+ /**
165
+ * Subscription-OAuth providers (`claude_code` / `chatgpt` / `kimi_code`)
166
+ * the user has connected via SOME local daemon. These have no cloud
167
+ * credential row — the daemon holds the credential — so this per-user
168
+ * marker is how `/v1/models` knows to LIST their models, making them
169
+ * configurable (fallback chains, prefs) from ANY machine. Live
170
+ * runnability is gated separately per-machine on daemon reachability
171
+ * (the dashboard shows "reconfigure on this machine" when the local
172
+ * daemon isn't connected). Set on connect; never auto-removed.
173
+ */
174
+ subscription_providers: S.optional(S.Array(S.String)),
175
+ /**
176
+ * Per-provider model picks for {@link MODEL_SELECTABLE_PROVIDERS}
177
+ * (provider → `provider_model_id`s). Absent entry = the curated catalog
178
+ * models only; present = exactly these ids. Listing only — routing an
179
+ * explicit id is unaffected.
180
+ */
181
+ provider_models: S.optional(S.Record(S.String, S.Array(S.String))),
182
+ /**
183
+ * What the user pays each month for the subscriptions above — declared
184
+ * by hand on the overview savings card, one row per connected provider.
185
+ * There is no vendor API that reports a plan tier, so the user picks it
186
+ * (`plan` is a catalog id like `max_5x`, or `custom` when they type the
187
+ * amount). `monthly_usd` is read only for `custom`; catalogued plans
188
+ * resolve their list price from the app's plan catalog so a price change
189
+ * ships as a code change. Drives the savings math: subscription spend is
190
+ * a COST, netted against what the same usage would have cost at metered
191
+ * API rates.
192
+ */
193
+ subscription_plans: S.optional(S.Array(SubscriptionPlanSelection)),
194
+ /**
195
+ * Default tier aliases (`ultra` / `plus` / `lite`) the user explicitly
196
+ * DELETED from the chains editor. Derivation of virtual default chains
197
+ * skips these — without the marker, a deleted derived chain would
198
+ * silently reappear on the next load. Removing the marker (re-adding
199
+ * the alias via the editor) reverts it to auto-derived.
200
+ */
201
+ disabled_default_aliases: S.optional(S.Array(DefaultTier)),
202
+ /**
203
+ * Opts the account out of contributing to the public aggregate usage index.
204
+ * Omitted means opted in.
205
+ */
206
+ public_usage_index_opt_out: S.optional(S.Boolean),
207
+ /**
208
+ * Account preference for daemon diagnostic reports. Omission defaults enabled
209
+ * after current cookie consent. Preserve on full-config writes; mutate only via the
210
+ * narrow `/api/user/daemon-diagnostics` contract.
211
+ */
212
+ daemon_diagnostics_opt_in: S.optional(S.Boolean),
213
+ /**
214
+ * Opaque policy epoch (UUID/hex). Minted on opt-in/opt-out and cookie-consent
215
+ * changes so a later enablement is a new reporting window. Full-config writes
216
+ * must preserve it.
217
+ */
218
+ daemon_diagnostics_policy_generation: S.optional(OpaqueId),
219
+ });
220
+ export type TExtraConfig = S.Schema.Type<typeof ExtraConfig>;
221
+
222
+ export const UserConfig = S.Struct({
223
+ fallback_groups: S.Array(FallbackGroup),
224
+ model_fallback_bindings: S.optional(S.Array(ModelFallbackBinding)),
225
+ extra: ExtraConfig,
226
+ });
227
+ export type TUserConfig = S.Schema.Type<typeof UserConfig>;
228
+
229
+ export const RequiredProviderTerm = S.Struct({
230
+ provider: S.String,
231
+ url: S.String,
232
+ version: S.String,
233
+ display_name: S.String,
234
+ });
235
+ export type TRequiredProviderTerm = S.Schema.Type<typeof RequiredProviderTerm>;
236
+
237
+ /**
238
+ * Admin-managed automatic chains, per tier, in the order they are tried.
239
+ * A tier that is absent (or empty) falls back to the catalog's
240
+ * `default_tiers` derivation. Each user still only gets the models whose
241
+ * provider they have connected.
242
+ */
243
+ export const DefaultTierChains = S.Struct({
244
+ ultra: S.optional(S.Array(S.String)),
245
+ plus: S.optional(S.Array(S.String)),
246
+ lite: S.optional(S.Array(S.String)),
247
+ });
248
+ export type TDefaultTierChains = S.Schema.Type<typeof DefaultTierChains>;
249
+
250
+ export const GlobalConfig = S.Struct({
251
+ terms_version: S.String,
252
+ terms_url: S.String,
253
+ privacy_url: S.String,
254
+ required_provider_terms: S.Array(RequiredProviderTerm),
255
+ default_aliases: S.Record(S.String, S.String),
256
+ model_catalog: S.Array(ExtendedModel),
257
+ search_provider: S.String,
258
+ default_tier_chains: S.optional(DefaultTierChains),
259
+ });
260
+ export type TGlobalConfig = S.Schema.Type<typeof GlobalConfig>;
261
+
262
+ // All stored credentials are API-key (BYOK); subscription OAuth lives on
263
+ // the local daemon, never the DB — so there's no kind/expiry/refresh here.
264
+ export const ProviderCredential = S.Struct({
265
+ provider: S.String,
266
+ has_credential: S.Boolean,
267
+ });
268
+ export type TProviderCredential = S.Schema.Type<typeof ProviderCredential>;
269
+
270
+ /**
271
+ * Body of `PATCH /api/config/user`: only what the caller changed.
272
+ *
273
+ * Omitted fields keep their stored value; an explicit `null` removes an
274
+ * optional field. `extra` is keyed loosely here because each field's
275
+ * schema already lives on {@link ExtraConfig}: the merged result is decoded
276
+ * as a whole {@link UserConfig}, so an unknown key or a bad value still
277
+ * fails the write.
278
+ */
279
+ export const UserConfigPatch = S.Struct({
280
+ fallback_groups: S.optional(S.Array(FallbackGroup)),
281
+ model_fallback_bindings: S.optional(S.NullOr(S.Array(ModelFallbackBinding))),
282
+ extra: S.optional(S.Record(S.String, S.Unknown)),
283
+ });
284
+ export type TUserConfigPatch = S.Schema.Type<typeof UserConfigPatch>;
285
+
286
+ const decodeUserConfig = S.decodeUnknownSync(UserConfig);
287
+
288
+ const sameValue = (a: unknown, b: unknown): boolean =>
289
+ JSON.stringify(a) === JSON.stringify(b);
290
+
291
+ /** Merge a patch onto the stored config; throws when the result is invalid. */
292
+ export const applyUserConfigPatch = (
293
+ stored: TUserConfig,
294
+ patch: TUserConfigPatch,
295
+ ): TUserConfig => {
296
+ const extra: Record<string, unknown> = { ...stored.extra };
297
+ for (const [key, value] of Object.entries(patch.extra ?? {})) {
298
+ if (value === null) delete extra[key];
299
+ else extra[key] = value;
300
+ }
301
+ const merged: Record<string, unknown> = {
302
+ ...stored,
303
+ ...(patch.fallback_groups !== undefined
304
+ ? { fallback_groups: patch.fallback_groups }
305
+ : {}),
306
+ extra,
307
+ };
308
+ if (patch.model_fallback_bindings === null) {
309
+ delete merged.model_fallback_bindings;
310
+ } else if (patch.model_fallback_bindings !== undefined) {
311
+ merged.model_fallback_bindings = patch.model_fallback_bindings;
312
+ }
313
+ return decodeUserConfig(merged);
314
+ };
315
+
316
+ /**
317
+ * The patch that turns `base` into `next`: changed fields only, removed
318
+ * optional fields as `null`. Callers edit a full config view and send this,
319
+ * so a stale page never overwrites fields it didn't touch.
320
+ */
321
+ export const diffUserConfig = (
322
+ base: TUserConfig,
323
+ next: TUserConfig,
324
+ ): TUserConfigPatch => {
325
+ const extra: Record<string, unknown> = {};
326
+ const keys = new Set([
327
+ ...Object.keys(base.extra),
328
+ ...Object.keys(next.extra),
329
+ ]);
330
+ for (const key of keys) {
331
+ const before = (base.extra as Record<string, unknown>)[key];
332
+ const after = (next.extra as Record<string, unknown>)[key];
333
+ if (sameValue(before, after)) continue;
334
+ extra[key] = after === undefined ? null : after;
335
+ }
336
+ return {
337
+ ...(sameValue(base.fallback_groups, next.fallback_groups)
338
+ ? {}
339
+ : { fallback_groups: next.fallback_groups }),
340
+ ...(sameValue(base.model_fallback_bindings, next.model_fallback_bindings)
341
+ ? {}
342
+ : { model_fallback_bindings: next.model_fallback_bindings ?? null }),
343
+ ...(Object.keys(extra).length > 0 ? { extra } : {}),
344
+ };
345
+ };
@@ -0,0 +1,115 @@
1
+ import { Schema as S } from "effect";
2
+ import { AccountIndex, DaemonCommandKind } from "./daemon";
3
+
4
+ // ─── Control channel — the live command lifecycle ────────────────────
5
+ //
6
+ // The stateless-relay contract: the relay is a pure socket binder (Browser
7
+ // WS ↔ Daemon WS) and the daemon is the source of truth. A command is a
8
+ // self-contained request → lifecycle → response with NO persistence — no
9
+ // `daemon_commands` mailbox, no history, no replay (it lives only as long as
10
+ // its sockets). This file owns the command lifecycle the browser drives its
11
+ // optimistic UI off; `device-state.ts` owns the snapshot the daemon pushes.
12
+ // See `docs/proposals/daemon-owned-state-stateless-relay.md`.
13
+ //
14
+ // NB: distinct from the daemon's local `packages/cli/daemon/src/control-channel.ts`
15
+ // (the partysocket transport impl). This is the SHARED wire contract both ends
16
+ // and the relay decode against.
17
+
18
+ export type { TDaemonCommand, TDaemonCommandKind } from "./daemon";
19
+ // Re-export the closed command vocabulary so a consumer can import the whole
20
+ // control-channel contract from one module.
21
+ export { DaemonCommand, DaemonCommandKind } from "./daemon";
22
+
23
+ /** Informational relay protocol version; feature gating is caps-based. */
24
+ export const RELAY_PROTOCOL_VERSION = 3;
25
+
26
+ /**
27
+ * The command lifecycle — daemon-asserted, pushed live over the socket.
28
+ * Replaces the old `DaemonCommandAck { status: "done" | "error" }` binary with
29
+ * a five-state progression:
30
+ *
31
+ * pending — browser → relay sent; no daemon ack yet (browser-local).
32
+ * ack — the daemon received the command and began running it.
33
+ * done — completed; the `-s` probe shows the box state actually changed.
34
+ * not_done — completed; the `-s` probe shows it was already in the desired
35
+ * state (a measured no-op). Reserved for a daemon-measured no-op —
36
+ * NEVER a transport rejection (an offline daemon yields `error`).
37
+ * error — failed (or the relay had no live daemon socket: `daemon_offline`);
38
+ * carries `message`.
39
+ *
40
+ * `done`/`not_done` for the install/uninstall family come from the pre/post
41
+ * `install.sh -s` probe (a measured fact, not a handler claim); commands with no
42
+ * `-s` probe (connect/logout/refresh/…) return them from the handler.
43
+ *
44
+ * Subscription login is NOT a CommandState. See `auth.ts` (`auth.login.*` /
45
+ * `auth.session.lost`) — do not overload this union with auth phases.
46
+ */
47
+ export const CommandState = S.Literals([
48
+ "pending",
49
+ "ack",
50
+ "done",
51
+ "not_done",
52
+ "error",
53
+ ]);
54
+ export type TCommandState = S.Schema.Type<typeof CommandState>;
55
+
56
+ /** The terminal subset of `CommandState` — the states a command finally rests
57
+ * in. `pending`/`ack` are transient. */
58
+ export const TerminalCommandState = S.Literals(["done", "not_done", "error"]);
59
+ export type TTerminalCommandState = S.Schema.Type<typeof TerminalCommandState>;
60
+
61
+ /**
62
+ * One snapshot of a command's progress. `req_id` is the id the browser minted at
63
+ * enqueue (the relay echoes it back — always present). `slug` is the command's
64
+ * target provider when it has one (connect/logout/…), so the browser can release
65
+ * the optimistic-pending ticket for THAT provider only — absent for whole-daemon
66
+ * commands (refresh/auto-update), where the browser falls back to clearing the
67
+ * key's tickets. `kind` is informational (display / dedup). `message` is a brief,
68
+ * human-readable line set on `error` (e.g. `daemon_offline`) and optionally on
69
+ * `not_done`.
70
+ */
71
+ export const CommandLifecycle = S.Struct({
72
+ req_id: S.String,
73
+ command_id: S.optional(S.String),
74
+ key_id: S.String,
75
+ daemon_session_id: S.optional(S.String),
76
+ slug: S.optional(S.String),
77
+ target: S.optional(S.String),
78
+ /**
79
+ * Device-local account slot this lifecycle clears in the dashboard
80
+ * (`docs/plan/multi-account-subscriptions.md`). Absent ⇒ account 0 so
81
+ * older relays / single-account tickets keep the bare `(keyId, slug)`
82
+ * pending key. Roster commands (`add_account` / `remove_account` /
83
+ * `pin_account`) leave this unset and scope via a `${slug}#roster`
84
+ * ticket instead.
85
+ */
86
+ account_index: S.optional(AccountIndex),
87
+ kind: DaemonCommandKind,
88
+ state: CommandState,
89
+ message: S.optional(S.String),
90
+ /**
91
+ * Optional command-specific payload (e.g. `list_local_sessions` →
92
+ * `{ sessions: LocalCliSession[] }`). Absent on most commands; the
93
+ * browser must ignore unknown shapes. Never carries secrets.
94
+ */
95
+ result: S.optional(S.Unknown),
96
+ });
97
+ export type TCommandLifecycle = S.Schema.Type<typeof CommandLifecycle>;
98
+
99
+ // ─── New relay → watcher frames (stateless-relay transport) ──────────
100
+ //
101
+ // These supersede the old `enqueue_ack` / `status_push` / `presence` frames in
102
+ // `relay.ts` once Phase 3 lands. Defined additively here so later phases import
103
+ // a stable contract; the full `RelayFrame` union swap happens with the relay
104
+ // rewrite.
105
+
106
+ /** relay → watcher. A live update on a command the watcher enqueued. The
107
+ * terminal frame (`done`/`not_done`/`error`) is the receipt — there is no
108
+ * durable row to read back. */
109
+ export const RelayCommandLifecycleFrame = S.Struct({
110
+ type: S.Literal("command_lifecycle"),
111
+ lifecycle: CommandLifecycle,
112
+ });
113
+ export type TRelayCommandLifecycleFrame = S.Schema.Type<
114
+ typeof RelayCommandLifecycleFrame
115
+ >;
@@ -0,0 +1,78 @@
1
+ import { Schema as S } from "effect";
2
+
3
+ export const CooldownReason = S.Literals([
4
+ "network",
5
+ "timeout",
6
+ "rate_limit",
7
+ "quota_exhausted",
8
+ "server_error",
9
+ "auth",
10
+ "payment",
11
+ "not_found",
12
+ "payload_too_large",
13
+ "unprocessable",
14
+ "request_invalid",
15
+ "accepted_unreadable",
16
+ "context_overflow",
17
+ "content_filter",
18
+ "upstream_rejection",
19
+ ]);
20
+ export type TCooldownReason = S.Schema.Type<typeof CooldownReason>;
21
+
22
+ export type THopAction =
23
+ | "retry_in_place"
24
+ | "cool_and_advance"
25
+ | "walk_no_cool"
26
+ | "surface";
27
+
28
+ /**
29
+ * The routing verb for a classified hop failure:
30
+ *
31
+ * - `retry_in_place` — transient infra fault; retry the SAME model once, then walk.
32
+ * - `cool_and_advance` — this model/account can't serve now (auth/quota/rate);
33
+ * cool it and hop to the next model. The ONLY cooling action, so whether a
34
+ * reason cools is exactly `action === "cool_and_advance"`, and `ttlMs` lives
35
+ * only on this variant.
36
+ * - `walk_no_cool` — the model is unavailable for this request but another might
37
+ * serve it (model absent / policy refusal / capability miss / oversized for
38
+ * THIS model); hop without cooling.
39
+ * - `surface` — stop on this hop (no hop, no cool, no retry). Covers
40
+ * request-deterministic failures (`request_invalid`, `unprocessable`) where
41
+ * every model would reject the request identically, and
42
+ * `accepted_unreadable` where the provider already accepted a 2xx the runner
43
+ * could not use (it may have billed — never re-send). On the cloud's ordered
44
+ * cloud↔device segment walk a `surface` reason ends the whole request, not
45
+ * only the current segment.
46
+ */
47
+ export type TCooldownPolicy =
48
+ | { readonly action: "retry_in_place" | "walk_no_cool" | "surface" }
49
+ | { readonly action: "cool_and_advance"; readonly ttlMs: number };
50
+
51
+ const cooldownPolicies = {
52
+ network: { action: "retry_in_place" },
53
+ timeout: { action: "retry_in_place" },
54
+ rate_limit: { action: "cool_and_advance", ttlMs: 180_000 },
55
+ quota_exhausted: { action: "cool_and_advance", ttlMs: 180_000 },
56
+ server_error: { action: "retry_in_place" },
57
+ auth: { action: "cool_and_advance", ttlMs: 60_000 },
58
+ payment: { action: "cool_and_advance", ttlMs: 60_000 },
59
+ // Model unavailable for this request, but a sibling may serve it — hop, no cool.
60
+ not_found: { action: "walk_no_cool" },
61
+ content_filter: { action: "walk_no_cool" },
62
+ // Oversized for THIS model; a larger-context sibling may still accept it.
63
+ payload_too_large: { action: "walk_no_cool" },
64
+ // Capability / unfamiliar 4xx: hop-local — another model may accept the same
65
+ // canonical request. Walk without cooling.
66
+ upstream_rejection: { action: "walk_no_cool" },
67
+ // Request-deterministic: the model works, the request is bad — surface, no hop.
68
+ unprocessable: { action: "surface" },
69
+ request_invalid: { action: "surface" },
70
+ // The provider answered with a non-error status we couldn't use: it accepted
71
+ // (and may have billed) the request, so another hop would bill it twice.
72
+ accepted_unreadable: { action: "surface" },
73
+ // Context overflow is intercepted before the action switch, so this is inert.
74
+ context_overflow: { action: "walk_no_cool" },
75
+ } satisfies Record<TCooldownReason, TCooldownPolicy>;
76
+
77
+ export const cooldownPolicyFor = (reason: TCooldownReason): TCooldownPolicy =>
78
+ cooldownPolicies[reason];
@@ -0,0 +1,10 @@
1
+ import { Schema as S } from "effect";
2
+
3
+ export const CostBreakdown = S.Struct({
4
+ input_cost_usd: S.Number,
5
+ output_cost_usd: S.Number,
6
+ cache_read_cost_usd: S.Number,
7
+ cache_write_cost_usd: S.Number,
8
+ total_cost_usd: S.Number,
9
+ });
10
+ export type TCostBreakdown = S.Schema.Type<typeof CostBreakdown>;
@@ -0,0 +1,31 @@
1
+ /** Parse a daemon port from an env-file compatible scalar. */
2
+ export const parseOpenllmDaemonPort = (
3
+ raw: string,
4
+ fallback: number,
5
+ ): number => {
6
+ const trimmed = raw.trim();
7
+ const wrapped = (s: string, q: string): boolean =>
8
+ s.length >= 2 && s.startsWith(q) && s.endsWith(q);
9
+ const deComment = (s: string): string =>
10
+ s.replace(/^(.*)\s#.*$/, "$1").trim();
11
+ // Order depends on WHERE the comment sits relative to the quotes:
12
+ // "59321 # local" → comment INSIDE quotes → unwrap first, then de-comment
13
+ // "59321" # local → comment OUTSIDE quotes → de-comment first, then unwrap
14
+ // 59321 # local → bare value with a trailing comment
15
+ let value: string;
16
+ if (wrapped(trimmed, '"') || wrapped(trimmed, "'")) {
17
+ value = deComment(trimmed.slice(1, -1));
18
+ } else {
19
+ const decommented = deComment(trimmed);
20
+ value =
21
+ wrapped(decommented, '"') || wrapped(decommented, "'")
22
+ ? decommented.slice(1, -1)
23
+ : decommented;
24
+ }
25
+ const stripped = value.trim();
26
+ if (!/^\d+$/.test(stripped)) return fallback;
27
+ const parsed = Number.parseInt(stripped, 10);
28
+ return Number.isInteger(parsed) && parsed >= 1 && parsed <= 65535
29
+ ? parsed
30
+ : fallback;
31
+ };