@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,547 @@
1
+ import {
2
+ decodeChannelEnvelope,
3
+ encodeChannelEnvelope,
4
+ stableChannelId,
5
+ } from "@openllmsh/sdk/tunnel/channel-envelope";
6
+ import type { TDuplex, TMuxChannel } from "@openllmsh/sdk/tunnel/mux";
7
+ import { createChannel } from "@openllmsh/sdk/tunnel/mux";
8
+ import type { TPeerLinkFailureCache } from "@openllmsh/sdk/tunnel/peer-link";
9
+ import {
10
+ createPeerLinkFailureCache,
11
+ peerLinkFailureReasonOf,
12
+ } from "@openllmsh/sdk/tunnel/peer-link";
13
+
14
+ type TActiveChannel = {
15
+ readonly channelId: string;
16
+ readonly keyId: string;
17
+ readonly channel: TMuxChannel;
18
+ state: "opening" | "open";
19
+ settle: ((channel: TMuxChannel | null) => void) | null;
20
+ readonly opening: Promise<TMuxChannel | null>;
21
+ sink: ((bytes: Uint8Array | null) => void) | null;
22
+ /**
23
+ * Whether `channel_open` carried a device-access grant. A warm / realtime
24
+ * open can cache a grant-less channel while the dpk is still unverified;
25
+ * agent later needs to replace that cache once a grant can be signed.
26
+ */
27
+ openedWithGrant: boolean;
28
+ };
29
+
30
+ export type TRelayMuxDependencies = {
31
+ readonly daemonAdvertisesMux: (keyId: string) => boolean;
32
+ /**
33
+ * True when this key requires a seed-derived device grant on
34
+ * `channel_open` (cloud provisioned OR daemon advertises `seedgate1`).
35
+ */
36
+ readonly needsSeedGate?: (keyId: string) => boolean;
37
+ /**
38
+ * Sign a device grant for `keyId` + `cid`. Returns the base64 envelope,
39
+ * or `null` when the vault is locked. Only called when `needsSeedGate`
40
+ * is true. A `null` result aborts the open (returns null) so a locked
41
+ * vault cannot open a seed-gated channel.
42
+ */
43
+ readonly signGrant?: (keyId: string, cid: string) => Promise<string | null>;
44
+ readonly relaySend: (frame: unknown) => boolean;
45
+ readonly relaySendBinary: (bytes: Uint8Array) => boolean;
46
+ readonly relayBufferedAmount: () => number;
47
+ readonly onRelayDrain: (callback: () => void) => () => void;
48
+ /**
49
+ * Stable browser identity for `stableChannelId` (device id + tab id). Host
50
+ * glue supplies this — the SDK never reads `localStorage` / cookies.
51
+ */
52
+ readonly browserIdentity: () => string;
53
+ };
54
+
55
+ export type TMuxPhase = "idle" | "opening" | "open" | "failed";
56
+
57
+ export type TMuxChannelState = {
58
+ readonly keyId: string;
59
+ readonly phase: TMuxPhase;
60
+ readonly channelId: string | null;
61
+ readonly lastError: string | null;
62
+ readonly failureCachedUntil: number | null;
63
+ };
64
+
65
+ /**
66
+ * Close reasons that must not stamp the failure cache. Kept in lockstep with
67
+ * RTC's benign set (`rtc-channel.ts` mountMux onClose) so presence-offline
68
+ * and intentional local teardown stay immediately retryable.
69
+ */
70
+ const isBenignMuxClose = (reason: string): boolean =>
71
+ reason === "done" ||
72
+ reason === "vault_locked" ||
73
+ reason === "daemon gone" ||
74
+ reason === "reset" ||
75
+ reason === "channel open aborted" ||
76
+ reason === "client closed";
77
+
78
+ export type TRelayMux = {
79
+ readonly clearMuxFailureForKey: (keyId: string) => void;
80
+ readonly getMuxChannelState: (keyId: string) => TMuxChannelState;
81
+ readonly subscribeMuxState: (listener: () => void) => () => void;
82
+ readonly onRelayBinary: (bytes: Uint8Array) => void;
83
+ readonly onRelayChannelAck: (frame: {
84
+ readonly channel_id: string;
85
+ readonly ok: boolean;
86
+ readonly error?: string;
87
+ }) => void;
88
+ readonly onRelayChannelClose: (frame: {
89
+ readonly channel_id: string;
90
+ readonly reason?: string;
91
+ }) => void;
92
+ readonly getOrOpenMuxChannel: (
93
+ keyId: string,
94
+ deps: TRelayMuxDependencies,
95
+ timeoutMs?: number,
96
+ signal?: AbortSignal,
97
+ ) => Promise<TMuxChannel | null>;
98
+ readonly dropChannelForKey: (keyId: string) => void;
99
+ readonly muxChannelOpenedWithGrant: (keyId: string) => boolean | null;
100
+ readonly dropGrantlessMuxChannelForKey: (keyId: string) => void;
101
+ readonly failAllMuxChannels: (reason: string) => void;
102
+ readonly clearMuxState: () => void;
103
+ };
104
+
105
+ export type TCreateRelayMuxOptions = {
106
+ /**
107
+ * Negative cache for this mux instance's opens. Defaults to a fresh cache so
108
+ * two `createRelayMux()` clients never share failure state. RTC host glue
109
+ * (`lib/stores/rtc-channel.ts`) and `createPeerLink` keep the process-global
110
+ * `peerLinkFailureCache` for the RTC rung — only the mux maps are scoped
111
+ * here. The browser app singleton (`lib/stores/relay-mux.ts`) is still one
112
+ * instance, so in-tab mux failure behaviour matches the old module singleton.
113
+ */
114
+ readonly failureCache?: TPeerLinkFailureCache;
115
+ };
116
+
117
+ /**
118
+ * Per-client relay-mux state. Two clients must not share channel maps — create
119
+ * one instance per client (or one app-wide singleton in host glue).
120
+ */
121
+ export const createRelayMux = (
122
+ options: TCreateRelayMuxOptions = {},
123
+ ): TRelayMux => {
124
+ const failureCache = options.failureCache ?? createPeerLinkFailureCache();
125
+ const channelsByKey = new Map<string, TActiveChannel>();
126
+ const channelsById = new Map<string, TActiveChannel>();
127
+ /**
128
+ * In-flight deterministic-id derivations keyed by daemon key id. Deriving the
129
+ * stable channel id is async, so without this a second synchronous same-key
130
+ * call would slip past the `channelsByKey` dedup before the first call's
131
+ * record is indexed — and the whole point of the stable id is that both
132
+ * derivations produce the SAME id, so they must share one open.
133
+ */
134
+ const pendingDerives = new Map<string, Promise<TMuxChannel | null>>();
135
+ /** UI diagnostics only; peer-link owns retry policy and cache lifetime. */
136
+ const stickyLastError = new Map<string, string>();
137
+ const muxListeners = new Set<() => void>();
138
+
139
+ const notifyMux = (): void => {
140
+ for (const listener of muxListeners) {
141
+ try {
142
+ listener();
143
+ } catch {
144
+ // never let a subscriber break the store
145
+ }
146
+ }
147
+ };
148
+
149
+ const cacheFailure = (keyId: string, reason?: string): void => {
150
+ const failure = peerLinkFailureReasonOf(
151
+ new Error(reason ?? "relay transport failure"),
152
+ );
153
+ failureCache.set(keyId, "mux", failure);
154
+ if (reason !== undefined && reason.length > 0) {
155
+ stickyLastError.set(keyId, reason);
156
+ }
157
+ notifyMux();
158
+ };
159
+
160
+ const failureCached = (keyId: string): boolean =>
161
+ failureCache.has(keyId, "mux");
162
+
163
+ const muxFailureCachedUntil = (keyId: string): number | null =>
164
+ failureCache.until(keyId, "mux");
165
+
166
+ const clearMuxFailureForKey = (keyId: string): void => {
167
+ failureCache.clear(keyId, "mux");
168
+ stickyLastError.delete(keyId);
169
+ notifyMux();
170
+ };
171
+
172
+ const getMuxChannelState = (keyId: string): TMuxChannelState => {
173
+ const failureCachedUntil = muxFailureCachedUntil(keyId);
174
+ const active = channelsByKey.get(keyId);
175
+ if (
176
+ active !== undefined &&
177
+ (active.state === "opening" || active.state === "open")
178
+ ) {
179
+ return {
180
+ keyId,
181
+ phase: active.state,
182
+ channelId: active.channelId,
183
+ lastError: stickyLastError.get(keyId) ?? null,
184
+ failureCachedUntil,
185
+ };
186
+ }
187
+ const sticky = stickyLastError.get(keyId) ?? null;
188
+ if (failureCachedUntil !== null || sticky !== null) {
189
+ return {
190
+ keyId,
191
+ phase: "failed",
192
+ channelId: null,
193
+ lastError: sticky,
194
+ failureCachedUntil,
195
+ };
196
+ }
197
+ return {
198
+ keyId,
199
+ phase: "idle",
200
+ channelId: null,
201
+ lastError: null,
202
+ failureCachedUntil: null,
203
+ };
204
+ };
205
+
206
+ const subscribeMuxState = (listener: () => void): (() => void) => {
207
+ muxListeners.add(listener);
208
+ return () => {
209
+ muxListeners.delete(listener);
210
+ };
211
+ };
212
+
213
+ const unindex = (channel: TActiveChannel): void => {
214
+ if (channelsByKey.get(channel.keyId) === channel)
215
+ channelsByKey.delete(channel.keyId);
216
+ if (channelsById.get(channel.channelId) === channel)
217
+ channelsById.delete(channel.channelId);
218
+ };
219
+
220
+ const makeRelayDuplex = (
221
+ channelId: string,
222
+ setSink: (sink: ((bytes: Uint8Array | null) => void) | null) => void,
223
+ deps: TRelayMuxDependencies,
224
+ ): TDuplex => ({
225
+ send: (bytes) => {
226
+ // channel_open text always precedes the first binary message; WebSocket
227
+ // preserves per-socket order, so relay admission cannot race payload bytes.
228
+ if (!deps.relaySendBinary(encodeChannelEnvelope(channelId, bytes))) {
229
+ // onClose (triggered by close) unindexes + settles + caches.
230
+ channelsById.get(channelId)?.channel.close("relay send failed");
231
+ }
232
+ },
233
+ bufferedAmount: deps.relayBufferedAmount,
234
+ highWaterMark: 1024 * 1024,
235
+ onDrain: deps.onRelayDrain,
236
+ onBytes: (callback) => setSink(callback),
237
+ close: () => {
238
+ setSink(null);
239
+ deps.relaySend({
240
+ type: "channel_close",
241
+ channel_id: channelId,
242
+ reason: "done",
243
+ });
244
+ },
245
+ });
246
+
247
+ const onRelayBinary = (bytes: Uint8Array): void => {
248
+ const envelope = decodeChannelEnvelope(bytes);
249
+ if (!envelope.ok) return;
250
+ const channel = channelsById.get(envelope.channelId);
251
+ if (channel === undefined) return;
252
+ const payload = envelope.payload;
253
+ if (payload.byteLength < 9) {
254
+ channel.channel.close("protocol_error");
255
+ return;
256
+ }
257
+ try {
258
+ channel.sink?.(payload);
259
+ } catch {
260
+ // Binary garbage must never destabilize the independent JSON control plane.
261
+ }
262
+ };
263
+
264
+ const onRelayChannelAck = (frame: {
265
+ readonly channel_id: string;
266
+ readonly ok: boolean;
267
+ readonly error?: string;
268
+ }): void => {
269
+ const channel = channelsById.get(frame.channel_id);
270
+ if (channel === undefined) return;
271
+ if (frame.ok) {
272
+ channel.state = "open";
273
+ stickyLastError.delete(channel.keyId);
274
+ const settle = channel.settle;
275
+ channel.settle = null;
276
+ settle?.(channel.channel);
277
+ notifyMux();
278
+ return;
279
+ }
280
+ // Non-benign error → onClose caches; teardown routed through close().
281
+ channel.channel.close(frame.error ?? "channel refused");
282
+ };
283
+
284
+ const onRelayChannelClose = (frame: {
285
+ readonly channel_id: string;
286
+ /** Open-vocabulary reason from a forward-compatible relay peer. */
287
+ readonly reason?: string;
288
+ }): void => {
289
+ channelsById
290
+ .get(frame.channel_id)
291
+ ?.channel.close(frame.reason ?? "channel closed");
292
+ };
293
+
294
+ const openMuxChannel = (
295
+ keyId: string,
296
+ channelId: string,
297
+ deps: TRelayMuxDependencies,
298
+ timeoutMs: number,
299
+ signal?: AbortSignal,
300
+ ): Promise<TMuxChannel | null> => {
301
+ let resolveOpening!: (channel: TMuxChannel | null) => void;
302
+ const opening = new Promise<TMuxChannel | null>((resolve) => {
303
+ resolveOpening = resolve;
304
+ });
305
+ const timer = setTimeout(
306
+ () => {
307
+ // onClose caches + settles; "channel open timed out" is non-benign.
308
+ channelsById.get(channelId)?.channel.close("channel open timed out");
309
+ },
310
+ Math.max(0, timeoutMs),
311
+ );
312
+ let removeAbortListener: (() => void) | undefined;
313
+ const settle = (result: TMuxChannel | null): void => {
314
+ clearTimeout(timer);
315
+ removeAbortListener?.();
316
+ resolveOpening(result);
317
+ };
318
+ // Channel-local close (protocol_error, peer_gone, host close, ack-nack,
319
+ // timeout) all route here — the single teardown. It unindexes, settles the
320
+ // pending open with null, and caches non-benign failures so a dead channel
321
+ // is never reused. Benign reasons stay immediately retryable.
322
+ let record!: TActiveChannel;
323
+ let sink: ((bytes: Uint8Array | null) => void) | null = null;
324
+ const channel = createChannel({
325
+ duplex: makeRelayDuplex(
326
+ channelId,
327
+ (next) => {
328
+ sink = next;
329
+ if (record !== undefined) record.sink = next;
330
+ },
331
+ deps,
332
+ ),
333
+ side: "consumer",
334
+ onClose: (reason) => {
335
+ if (record === undefined) return;
336
+ unindex(record);
337
+ const pending = record.settle;
338
+ record.settle = null;
339
+ if (pending !== null) settle(null);
340
+ // vault_locked is immediately retryable (no failure cache) but still sticky
341
+ // so the UI can show "unlock to connect" after teardown.
342
+ if (reason === "vault_locked") {
343
+ stickyLastError.set(keyId, reason);
344
+ notifyMux();
345
+ } else if (!isBenignMuxClose(reason)) {
346
+ cacheFailure(keyId, reason);
347
+ } else {
348
+ notifyMux();
349
+ }
350
+ },
351
+ });
352
+ record = {
353
+ channelId,
354
+ keyId,
355
+ channel,
356
+ state: "opening",
357
+ settle,
358
+ opening,
359
+ sink,
360
+ openedWithGrant: false,
361
+ };
362
+ channelsByKey.set(keyId, record);
363
+ channelsById.set(channelId, record);
364
+ if (signal !== undefined) {
365
+ const abort = (): void => channel.close("channel open aborted");
366
+ signal.addEventListener("abort", abort, { once: true });
367
+ removeAbortListener = (): void =>
368
+ signal.removeEventListener("abort", abort);
369
+ if (signal.aborted) abort();
370
+ }
371
+ notifyMux();
372
+
373
+ const sendOpen = (grant: string | undefined): void => {
374
+ record.openedWithGrant = grant !== undefined;
375
+ if (
376
+ !deps.relaySend({
377
+ type: "channel_open",
378
+ channel_id: channelId,
379
+ key_id: keyId,
380
+ ...(grant !== undefined ? { grant } : {}),
381
+ })
382
+ ) {
383
+ channel.close("relay send failed");
384
+ }
385
+ };
386
+
387
+ // Seed-gated path: prefer a signed grant before sending channel_open.
388
+ // Without a control-key signer, still send a grant-less open so
389
+ // non-gated kinds (realtime) keep working; the daemon's per-kind
390
+ // seedgate rejects agent/RTC that require a grant.
391
+ if (deps.needsSeedGate?.(keyId) === true) {
392
+ const sign = deps.signGrant;
393
+ if (sign === undefined) {
394
+ sendOpen(undefined);
395
+ return opening;
396
+ }
397
+ void sign(keyId, channelId)
398
+ .then((grant) => {
399
+ if (channelsById.get(channelId) !== record) return;
400
+ if (grant === null) {
401
+ sendOpen(undefined);
402
+ return;
403
+ }
404
+ sendOpen(grant);
405
+ })
406
+ .catch((error: unknown) => {
407
+ // Signer threw (cache drift, unknown daemon pubkey, …). For agent
408
+ // the open will still fail at the daemon; surface the reason on
409
+ // the channel so the UI can distinguish unverified / not-verified.
410
+ if (channelsById.get(channelId) !== record) return;
411
+ const reason =
412
+ error instanceof Error && error.message.length > 0
413
+ ? error.message
414
+ : "vault_locked";
415
+ // device_not_verified: fall through to a grant-less open so
416
+ // non-agent kinds (realtime / tunnel) keep working; the daemon's
417
+ // per-kind seedgate still rejects agent without a verified dpk.
418
+ // browser_unverified / device_identity_changed: fail closed — the
419
+ // browser cannot usefully open, or the pin has rotated under us.
420
+ if (
421
+ reason === "device_identity_changed" ||
422
+ reason === "browser_unverified"
423
+ ) {
424
+ channel.close(reason);
425
+ return;
426
+ }
427
+ sendOpen(undefined);
428
+ });
429
+ return opening;
430
+ }
431
+
432
+ sendOpen(undefined);
433
+ return opening;
434
+ };
435
+
436
+ const getOrOpenMuxChannel = (
437
+ keyId: string,
438
+ deps: TRelayMuxDependencies,
439
+ timeoutMs = 15_000,
440
+ signal?: AbortSignal,
441
+ ): Promise<TMuxChannel | null> => {
442
+ if (signal?.aborted) return Promise.resolve(null);
443
+ if (!deps.daemonAdvertisesMux(keyId) || failureCached(keyId)) {
444
+ return Promise.resolve(null);
445
+ }
446
+ const existing = channelsByKey.get(keyId);
447
+ if (existing !== undefined) {
448
+ return existing.state === "opening"
449
+ ? existing.opening
450
+ : Promise.resolve(existing.state === "open" ? existing.channel : null);
451
+ }
452
+ const pending = pendingDerives.get(keyId);
453
+ if (pending !== undefined) return pending;
454
+
455
+ // Deterministic channel identity: a relay-socket reconnect in this tab
456
+ // re-derives the SAME id for its (browser device, tab → daemon key) tuple,
457
+ // while another tab gets an independent channel. The relay authenticates the
458
+ // socket server-side and already trusts the channelId's owner, so `keyId`
459
+ // (globally unique, user-scoped server-side) stands in for both identity
460
+ // args. The composite preserves device identity without using the tunnel
461
+ // identity delimiter within a value.
462
+ const opening = Promise.resolve()
463
+ .then(() => stableChannelId(keyId, keyId, deps.browserIdentity(), 0))
464
+ .then((channelId) => {
465
+ // A same-key open may have won the race while this derivation was in
466
+ // flight — re-check before indexing a second record.
467
+ const winner = channelsByKey.get(keyId);
468
+ if (winner !== undefined) return winner.opening;
469
+ return openMuxChannel(keyId, channelId, deps, timeoutMs, signal);
470
+ })
471
+ .catch(() => null);
472
+ pendingDerives.set(keyId, opening);
473
+ void opening.finally(() => {
474
+ if (pendingDerives.get(keyId) === opening) pendingDerives.delete(keyId);
475
+ });
476
+ return opening;
477
+ };
478
+
479
+ const dropChannelForKey = (keyId: string): void => {
480
+ clearMuxFailureForKey(keyId);
481
+ channelsByKey.get(keyId)?.channel.close("daemon gone");
482
+ };
483
+
484
+ /**
485
+ * Whether the cached mux channel for `keyId` was opened with a device-access
486
+ * grant. `null` when nothing is cached.
487
+ */
488
+ const muxChannelOpenedWithGrant = (keyId: string): boolean | null => {
489
+ const existing = channelsByKey.get(keyId);
490
+ if (existing === undefined) return null;
491
+ return existing.openedWithGrant;
492
+ };
493
+
494
+ /**
495
+ * Drop a cached grant-less channel so the next open can send a grant. No-op
496
+ * when nothing is cached or the channel already carried a grant. Used by the
497
+ * agent path once a verified dpk is available; non-agent kinds leave
498
+ * grant-less channels alone.
499
+ *
500
+ * The channel is shared across kinds (tunnel / realtime / agent). Close only
501
+ * when idle — active streams or an in-flight `channel_open` leave it alone so
502
+ * a concurrent non-agent stream is not torn down under the agent dial.
503
+ */
504
+ const dropGrantlessMuxChannelForKey = (keyId: string): void => {
505
+ const existing = channelsByKey.get(keyId);
506
+ if (existing === undefined || existing.openedWithGrant) return;
507
+ if (
508
+ existing.state === "opening" ||
509
+ existing.channel.openStreamCount() > 0
510
+ ) {
511
+ return;
512
+ }
513
+ clearMuxFailureForKey(keyId);
514
+ // "reset" is benign — immediately retryable, no failure cache.
515
+ existing.channel.close("reset");
516
+ };
517
+
518
+ const failAllMuxChannels = (reason: string): void => {
519
+ for (const channel of [...channelsByKey.values()])
520
+ channel.channel.close(reason);
521
+ };
522
+
523
+ const clearMuxState = (): void => {
524
+ failAllMuxChannels("relay socket closed");
525
+ channelsByKey.clear();
526
+ channelsById.clear();
527
+ pendingDerives.clear();
528
+ failureCache.clearPath("mux");
529
+ stickyLastError.clear();
530
+ notifyMux();
531
+ };
532
+
533
+ return {
534
+ clearMuxFailureForKey,
535
+ getMuxChannelState,
536
+ subscribeMuxState,
537
+ onRelayBinary,
538
+ onRelayChannelAck,
539
+ onRelayChannelClose,
540
+ getOrOpenMuxChannel,
541
+ dropChannelForKey,
542
+ muxChannelOpenedWithGrant,
543
+ dropGrantlessMuxChannelForKey,
544
+ failAllMuxChannels,
545
+ clearMuxState,
546
+ };
547
+ };
@@ -0,0 +1,51 @@
1
+ /**
2
+ * Host-injected I/O seams for `@openllmsh/sdk/client`. The SDK stays sans-I/O;
3
+ * browser hosts pass globals, CLI/daemon hosts pass Bun / werift equivalents.
4
+ */
5
+
6
+ /** Minimal WebSocket constructor shape (browser `WebSocket` or a polyfill). */
7
+ export type TWebSocketConstructor = {
8
+ new (url: string, protocols?: string | string[]): WebSocket;
9
+ readonly CONNECTING: number;
10
+ readonly OPEN: number;
11
+ readonly CLOSING: number;
12
+ readonly CLOSED: number;
13
+ };
14
+
15
+ /**
16
+ * RTC peer-connection factory. Concrete options stay with the tunnel layer;
17
+ * the client only needs a constructor-like callable the host supplies.
18
+ */
19
+ export type TRtcFactory = (config?: RTCConfiguration) => RTCPeerConnection;
20
+
21
+ export type TClientTransport = {
22
+ /**
23
+ * Host fetch. Signature matches `openapi/call.ts` (`input: string`) so CLI
24
+ * test doubles and memory-hook transports type-check without wrappers.
25
+ */
26
+ readonly fetch: (input: string, init?: RequestInit) => Promise<Response>;
27
+ readonly websocket: TWebSocketConstructor;
28
+ readonly rtc?: TRtcFactory;
29
+ };
30
+
31
+ export type TCreateClientOptions = {
32
+ /** Cloud origin, e.g. `https://openllm.sh`. Trailing slashes are stripped. */
33
+ readonly origin: string;
34
+ /**
35
+ * `sk-llm-…` API key. May be empty while a CLI-auth claim is still opening
36
+ * the sealed key; vault methods that need a DEK or key id then fail clearly.
37
+ */
38
+ readonly apiKey: string;
39
+ readonly transport: TClientTransport;
40
+ /**
41
+ * Optional already-unwrapped DEK (browser host glue after PIN/passkey unlock).
42
+ * The client copies the bytes and zeros its copy on {@link TOpenllmClient.close}.
43
+ */
44
+ readonly dek?: Uint8Array;
45
+ /**
46
+ * Optional `dek_for_key` column. When set with a valid `apiKey`, the vault
47
+ * session unwraps the DEK during {@link import("./vault").TClientVault.unlockFromApiKey}
48
+ * (callers invoke that explicitly — `createClient` stays sync).
49
+ */
50
+ readonly dekForKey?: string;
51
+ };