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

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,324 @@
1
+ /**
2
+ * Realtime (voice) duplex session vocabulary — the supported subset only.
3
+ *
4
+ * Scope note: only Grok's text-to-audio realtime connection is live-verified
5
+ * (`docs/research/subscription-provider-capabilities-2026-09-17.md`,
6
+ * "Verified realtime audio output"). Audio INPUT, barge-in, and any event
7
+ * outside the closed unions below are deliberately unmodeled — an unknown or
8
+ * unsupported event is rejected by the parser, never forwarded blind. Widen
9
+ * this file (new literals, new event variants) only after a live probe
10
+ * verifies the addition; do not speculatively add vendor fields.
11
+ *
12
+ * Transport: this is payload vocabulary only. The mux `kind:"realtime"` OPEN
13
+ * envelope lives in `./mux` (`RealtimeStreamOpenPayload`, folded into
14
+ * `StreamOpenPayload`); the dedicated `realtime1` duplex capability is
15
+ * `REALTIME_DUPLEX_CAP` in `./mux`. Once a stream is open, client/server
16
+ * events defined here ride NDJSON-framed (one JSON value per `\n`-terminated
17
+ * line) over the stream's flow-controlled DATA channel — see
18
+ * `@openllmsh/sdk/tunnel/streams`'s `pumpRealtimeEvents` / `sendRealtimeEvent` /
19
+ * `realtimeStream`, which import the bounds and parsers below rather than
20
+ * duplicating them.
21
+ */
22
+
23
+ import { Schema as S } from "effect";
24
+ import * as Result from "effect/Result";
25
+ import { GROK_TTS_VOICES } from "./audio";
26
+ import { REALTIME_MODEL_IDS } from "./realtime-generated";
27
+
28
+ /**
29
+ * Hard per-session lifetime. The daemon (and the consumer-side helper) both
30
+ * RESET the stream with `timeout` once reached, regardless of activity —
31
+ * shared here so neither side can drift from the other's bound.
32
+ */
33
+ export const REALTIME_SESSION_MAX_LIFETIME_MS = 10 * 60 * 1000;
34
+
35
+ /** Liveness heartbeat cadence once a realtime session is open. Either peer
36
+ * may send `{t:"heartbeat"}` (a mux CTRL frame, `StreamCtrlPayload` in
37
+ * `./mux`); missing ALL inbound traffic (heartbeat or otherwise) for
38
+ * {@link REALTIME_HEARTBEAT_TIMEOUT_MS} RESETs with `timeout`. */
39
+ export const REALTIME_HEARTBEAT_INTERVAL_MS = 15_000;
40
+ export const REALTIME_HEARTBEAT_TIMEOUT_MS = 45_000;
41
+
42
+ /**
43
+ * Bound on ONE NDJSON realtime event line (JSON-encoded, UTF-8 bytes,
44
+ * including the trailing `\n`). Vendor audio deltas are small PCM chunks (a
45
+ * few KB base64 per the research probe's 107,048-byte total across many
46
+ * deltas) — this is a generous ceiling, not the expected size. A line (or an
47
+ * unterminated remainder) over this bound is a bounded-queue overflow, never
48
+ * a growing buffer.
49
+ */
50
+ export const REALTIME_MAX_EVENT_BYTES = 64 * 1024;
51
+ export const REALTIME_MAX_LINE_BYTES = REALTIME_MAX_EVENT_BYTES;
52
+
53
+ /**
54
+ * Bound on in-flight (parsed, not-yet-delivered-to-consumer) server events a
55
+ * daemon-side realtime session holds before treating a slow consumer as
56
+ * `lagging` and ending the session — the realtime counterpart of the PTY
57
+ * session's bounded output queue. Shared so the daemon's queue and any
58
+ * future consumer-side queue agree on one number.
59
+ */
60
+ export const REALTIME_MAX_QUEUED_EVENTS = 64;
61
+
62
+ /** Bound on one `conversation.item.create` `input_text` value. */
63
+ export const REALTIME_MAX_INPUT_TEXT_LENGTH = 4_000;
64
+
65
+ /**
66
+ * Subscription realtime providers with a LIVE-VERIFIED connection. Grok only
67
+ * — see the module doc. Widening this is a protocol change, not a client
68
+ * toggle.
69
+ */
70
+ export const RealtimeProvider = S.Literal("grok");
71
+ export type TRealtimeProvider = S.Schema.Type<typeof RealtimeProvider>;
72
+
73
+ /**
74
+ * The realtime model verified against `wss://api.x.ai/v1/realtime`.
75
+ *
76
+ * The id set is CATALOG-OWNED: it comes from `./realtime-generated`, a tiny
77
+ * artifact derived from the catalog rows declaring `capabilities:
78
+ * ["realtime"]`. It stays a generated literal rather than a runtime lookup
79
+ * because the SHIPPED daemon binary decodes this schema at mux admission —
80
+ * `protocol` cannot import `packages/api`, and a runtime read would add a
81
+ * daemon -> API dependency and break decode compat with deployed binaries.
82
+ * `bun run check:realtime-generated` fails on drift. Widening the set is a
83
+ * catalog change, not a client toggle.
84
+ */
85
+ export const RealtimeModel = S.Literals(REALTIME_MODEL_IDS);
86
+ export type TRealtimeModel = S.Schema.Type<typeof RealtimeModel>;
87
+
88
+ /** Reuses the verified Grok TTS voice list — never duplicate that literal. */
89
+ export const RealtimeVoice = S.Literals(GROK_TTS_VOICES);
90
+ export type TRealtimeVoice = S.Schema.Type<typeof RealtimeVoice>;
91
+
92
+ /** Only PCM16 at 24kHz was exercised on the realtime connection. */
93
+ export const RealtimeOutputAudioFormat = S.Literal("pcm16_24khz");
94
+ export type TRealtimeOutputAudioFormat = S.Schema.Type<
95
+ typeof RealtimeOutputAudioFormat
96
+ >;
97
+
98
+ /**
99
+ * Mux `kind:"realtime"` OPEN payload — folded into `StreamOpenPayload` in
100
+ * `./mux`. Declaring `voice`/`model` here (not only inside `session.update`)
101
+ * lets the serving daemon refuse an unsupported combination before it ever
102
+ * dials the vendor.
103
+ */
104
+ export const RealtimeStreamOpenPayload = S.Struct({
105
+ kind: S.Literal("realtime"),
106
+ provider: RealtimeProvider,
107
+ model: RealtimeModel,
108
+ voice: RealtimeVoice,
109
+ });
110
+ export type TRealtimeStreamOpenPayload = S.Schema.Type<
111
+ typeof RealtimeStreamOpenPayload
112
+ >;
113
+
114
+ // ---------------------------------------------------------------------------
115
+ // Client → server events (the consumer sends these)
116
+ // ---------------------------------------------------------------------------
117
+
118
+ /** Disabled server-side turn detection — the only mode verified (text input
119
+ * only; no microphone/VAD turn-taking has been tested). */
120
+ const RealtimeTurnDetectionDisabled = S.Struct({ type: S.Null });
121
+
122
+ export const RealtimeSessionUpdateEvent = S.Struct({
123
+ type: S.Literal("session.update"),
124
+ session: S.Struct({
125
+ voice: RealtimeVoice,
126
+ output_audio_format: RealtimeOutputAudioFormat,
127
+ turn_detection: RealtimeTurnDetectionDisabled,
128
+ }),
129
+ });
130
+ export type TRealtimeSessionUpdateEvent = S.Schema.Type<
131
+ typeof RealtimeSessionUpdateEvent
132
+ >;
133
+
134
+ const RealtimeInputTextContent = S.Struct({
135
+ type: S.Literal("input_text"),
136
+ text: S.String.check(
137
+ S.isMinLength(1),
138
+ S.isMaxLength(REALTIME_MAX_INPUT_TEXT_LENGTH),
139
+ ),
140
+ });
141
+
142
+ /** Text-only conversation item — audio input is unmodeled (module doc). */
143
+ export const RealtimeConversationItemCreateEvent = S.Struct({
144
+ type: S.Literal("conversation.item.create"),
145
+ item: S.Struct({
146
+ type: S.Literal("message"),
147
+ role: S.Literal("user"),
148
+ content: S.Array(RealtimeInputTextContent).check(
149
+ S.isMinLength(1),
150
+ S.isMaxLength(1),
151
+ ),
152
+ }),
153
+ });
154
+ export type TRealtimeConversationItemCreateEvent = S.Schema.Type<
155
+ typeof RealtimeConversationItemCreateEvent
156
+ >;
157
+
158
+ export const RealtimeResponseCreateEvent = S.Struct({
159
+ type: S.Literal("response.create"),
160
+ });
161
+ export type TRealtimeResponseCreateEvent = S.Schema.Type<
162
+ typeof RealtimeResponseCreateEvent
163
+ >;
164
+
165
+ /** The entire supported client→server vocabulary. Anything else fails to
166
+ * parse and is dropped rather than forwarded upstream. */
167
+ export const RealtimeClientEvent = S.Union([
168
+ RealtimeSessionUpdateEvent,
169
+ RealtimeConversationItemCreateEvent,
170
+ RealtimeResponseCreateEvent,
171
+ ]);
172
+ export type TRealtimeClientEvent = S.Schema.Type<typeof RealtimeClientEvent>;
173
+
174
+ // ---------------------------------------------------------------------------
175
+ // Server → client events (the vendor, normalized, sends these)
176
+ // ---------------------------------------------------------------------------
177
+
178
+ export const RealtimeSessionCreatedEvent = S.Struct({
179
+ type: S.Literal("session.created"),
180
+ });
181
+ export const RealtimeSessionUpdatedEvent = S.Struct({
182
+ type: S.Literal("session.updated"),
183
+ });
184
+ export const RealtimeResponseCreatedEvent = S.Struct({
185
+ type: S.Literal("response.created"),
186
+ });
187
+
188
+ export const RealtimeResponseOutputAudioDeltaEvent = S.Struct({
189
+ type: S.Literal("response.output_audio.delta"),
190
+ /** Base64-encoded PCM16/24kHz chunk. */
191
+ delta: S.String.check(
192
+ S.isMinLength(1),
193
+ S.isMaxLength(REALTIME_MAX_EVENT_BYTES),
194
+ ),
195
+ });
196
+ export const RealtimeResponseOutputAudioTranscriptDeltaEvent = S.Struct({
197
+ type: S.Literal("response.output_audio_transcript.delta"),
198
+ delta: S.String.check(S.isMaxLength(REALTIME_MAX_EVENT_BYTES)),
199
+ });
200
+ export const RealtimeResponseOutputAudioDoneEvent = S.Struct({
201
+ type: S.Literal("response.output_audio.done"),
202
+ });
203
+ export const RealtimeResponseDoneEvent = S.Struct({
204
+ type: S.Literal("response.done"),
205
+ });
206
+
207
+ /** Normalized refusal/failure surfaced to the consumer in-band (distinct
208
+ * from a mux-level RESET, which ends the whole stream). */
209
+ export const RealtimeErrorEvent = S.Struct({
210
+ type: S.Literal("error"),
211
+ code: S.String.check(S.isMinLength(1), S.isMaxLength(64)),
212
+ message: S.optional(S.String.check(S.isMaxLength(256))),
213
+ });
214
+ export type TRealtimeErrorEvent = S.Schema.Type<typeof RealtimeErrorEvent>;
215
+
216
+ /** The entire supported server→client vocabulary. An unrecognized vendor
217
+ * event (or a shape that doesn't match one of these) is DROPPED by the
218
+ * daemon, never relayed verbatim — see `realtime-session.ts`. */
219
+ export const RealtimeServerEvent = S.Union([
220
+ RealtimeSessionCreatedEvent,
221
+ RealtimeSessionUpdatedEvent,
222
+ RealtimeResponseCreatedEvent,
223
+ RealtimeResponseOutputAudioDeltaEvent,
224
+ RealtimeResponseOutputAudioTranscriptDeltaEvent,
225
+ RealtimeResponseOutputAudioDoneEvent,
226
+ RealtimeResponseDoneEvent,
227
+ RealtimeErrorEvent,
228
+ ]);
229
+ export type TRealtimeServerEvent = S.Schema.Type<typeof RealtimeServerEvent>;
230
+
231
+ const parse = <T>(schema: S.ConstraintDecoder<T>, value: unknown): T | null => {
232
+ const result = S.decodeUnknownResult(schema)(value);
233
+ return Result.isSuccess(result) ? result.success : null;
234
+ };
235
+
236
+ export const parseRealtimeClientEvent = (
237
+ value: unknown,
238
+ ): TRealtimeClientEvent | null => parse(RealtimeClientEvent, value);
239
+
240
+ export const parseRealtimeServerEvent = (
241
+ value: unknown,
242
+ ): TRealtimeServerEvent | null => parse(RealtimeServerEvent, value);
243
+
244
+ // ---------------------------------------------------------------------------
245
+ // NDJSON line framing over the mux DATA channel
246
+ // ---------------------------------------------------------------------------
247
+
248
+ const lineEncoder = new TextEncoder();
249
+ const lineDecoder = new TextDecoder();
250
+ const NEWLINE = 0x0a;
251
+
252
+ /**
253
+ * Encode one realtime event as an NDJSON line (`JSON.stringify(event) +
254
+ * "\n"`, UTF-8). Returns null on a non-serializable value or when the
255
+ * encoded line would exceed {@link REALTIME_MAX_LINE_BYTES} — callers must
256
+ * treat either as "do not send", never truncate.
257
+ */
258
+ export const encodeRealtimeEventLine = (event: unknown): Uint8Array | null => {
259
+ let text: string;
260
+ try {
261
+ text = JSON.stringify(event);
262
+ } catch {
263
+ return null;
264
+ }
265
+ if (text === undefined) return null;
266
+ const encoded = lineEncoder.encode(`${text}\n`);
267
+ if (encoded.byteLength > REALTIME_MAX_LINE_BYTES) return null;
268
+ return encoded;
269
+ };
270
+
271
+ /** Decode one NDJSON line's raw bytes into an unknown JSON value, or
272
+ * `undefined` on malformed UTF-8/JSON. */
273
+ export const decodeRealtimeLine = (line: Uint8Array): unknown | undefined => {
274
+ try {
275
+ return JSON.parse(lineDecoder.decode(line));
276
+ } catch {
277
+ return undefined;
278
+ }
279
+ };
280
+
281
+ export type TRealtimeLineSplitResult = {
282
+ readonly lines: readonly Uint8Array[];
283
+ readonly remainder: Uint8Array;
284
+ };
285
+
286
+ /**
287
+ * Append `chunk` to a carried-over `remainder` and split on `\n`. Pure and
288
+ * allocation-bounded: the transient `combined` buffer is at most
289
+ * `remainder.byteLength + chunk.byteLength`, and this function is called
290
+ * once per inbound DATA frame (already bounded to the mux's own
291
+ * `MAX_PAYLOAD_BYTES`), so a caller that rejects a null result before the
292
+ * next call never accumulates past one frame beyond the line bound.
293
+ *
294
+ * Returns null when EITHER a newline-terminated segment OR the trailing
295
+ * not-yet-terminated remainder would exceed {@link REALTIME_MAX_LINE_BYTES}
296
+ * — callers MUST treat that as a bounded-queue overflow (RESET `lagging`),
297
+ * never grow the buffer further. Checking only the tail is not enough: the
298
+ * mux's own `MAX_PAYLOAD_BYTES` (256 KiB) is larger than
299
+ * `REALTIME_MAX_LINE_BYTES` (64 KiB), so a single inbound DATA frame can by
300
+ * itself carry a newline-terminated segment well past the line bound —
301
+ * that segment must be rejected before it is ever handed to
302
+ * `decodeRealtimeLine`/`JSON.parse`, not silently accepted because it
303
+ * happened to end in `\n`.
304
+ */
305
+ export const splitRealtimeLines = (
306
+ remainder: Uint8Array,
307
+ chunk: Uint8Array,
308
+ ): TRealtimeLineSplitResult | null => {
309
+ const combined = new Uint8Array(remainder.byteLength + chunk.byteLength);
310
+ combined.set(remainder, 0);
311
+ combined.set(chunk, remainder.byteLength);
312
+ const lines: Uint8Array[] = [];
313
+ let start = 0;
314
+ for (let i = 0; i < combined.byteLength; i += 1) {
315
+ if (combined[i] === NEWLINE) {
316
+ if (i - start > REALTIME_MAX_LINE_BYTES) return null;
317
+ lines.push(combined.subarray(start, i));
318
+ start = i + 1;
319
+ }
320
+ }
321
+ const tail = combined.subarray(start);
322
+ if (tail.byteLength > REALTIME_MAX_LINE_BYTES) return null;
323
+ return { lines, remainder: tail };
324
+ };
@@ -0,0 +1,118 @@
1
+ /**
2
+ * Pure registry-pointer identity validation — shared by the gateway
3
+ * (`@openllm/registry` re-exports these) and the daemon's integration
4
+ * executor. String-only: no crypto, fs, or fetch, so it stays inside the
5
+ * daemon's protocol+wire dependency budget.
6
+ */
7
+
8
+ export const REGISTRY_REPOSITORY = "openllmsh/registry";
9
+ export const SHA256_RE = /^[0-9a-f]{64}$/;
10
+ export const FULL_COMMIT_SHA_RE = /^[0-9a-f]{40}$/;
11
+ const INSTALL_STAMP_RE = /^# openllm-self-sha256: ([0-9a-f]{64})$/gm;
12
+
13
+ /** Read the one canonical install-stamp identity embedded in an assembled script. */
14
+ export const readRegistryInstallStampSha256 = (
15
+ bytes: Uint8Array,
16
+ ): string | null => {
17
+ let script: string;
18
+ try {
19
+ script = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
20
+ } catch {
21
+ return null;
22
+ }
23
+ const matches = [...script.matchAll(INSTALL_STAMP_RE)];
24
+ return matches.length === 1 ? matches[0][1] : null;
25
+ };
26
+
27
+ export type TRegistryPointerFilename = "install.sh" | "pointer.json";
28
+
29
+ export type TRegistryPointerLocation = {
30
+ readonly commit: string;
31
+ readonly area: "setup";
32
+ readonly slug: string;
33
+ readonly filename: TRegistryPointerFilename;
34
+ };
35
+
36
+ export const registryRawUrl = (
37
+ commit: string,
38
+ area: "setup",
39
+ slug: string,
40
+ filename: TRegistryPointerFilename,
41
+ ): string => {
42
+ if (!FULL_COMMIT_SHA_RE.test(commit)) {
43
+ throw new Error(`registry commit must be a full lowercase SHA: ${commit}`);
44
+ }
45
+ if (!/^[a-z0-9-]+$/.test(slug)) {
46
+ throw new Error(`invalid registry slug: ${slug}`);
47
+ }
48
+ return `https://raw.githubusercontent.com/${REGISTRY_REPOSITORY}/${commit}/${area}/${slug}/${filename}`;
49
+ };
50
+
51
+ export const validateRegistryRawUrl = (
52
+ value: string,
53
+ expected: {
54
+ readonly area: "setup";
55
+ readonly slug: string;
56
+ readonly filename: TRegistryPointerFilename;
57
+ },
58
+ ): TRegistryPointerLocation => {
59
+ let url: URL;
60
+ try {
61
+ url = new URL(value);
62
+ } catch {
63
+ throw new Error("registry URL is malformed");
64
+ }
65
+
66
+ if (url.protocol !== "https:") throw new Error("registry URL must use HTTPS");
67
+ if (url.hostname !== "raw.githubusercontent.com") {
68
+ throw new Error("registry URL host is not approved");
69
+ }
70
+ if (
71
+ url.username !== "" ||
72
+ url.password !== "" ||
73
+ url.port !== "" ||
74
+ url.search !== "" ||
75
+ url.hash !== ""
76
+ ) {
77
+ throw new Error("registry URL contains forbidden authority or suffix data");
78
+ }
79
+
80
+ // Exact canonical layout: a leading empty segment then six non-empty parts.
81
+ // No filter(Boolean) — duplicate or trailing slashes must be rejected, not
82
+ // silently collapsed into a passing shape.
83
+ const rawSegments = url.pathname.split("/");
84
+ if (
85
+ rawSegments.length !== 7 ||
86
+ rawSegments[0] !== "" ||
87
+ rawSegments.slice(1).some((segment) => segment === "")
88
+ ) {
89
+ throw new Error("registry URL path is invalid");
90
+ }
91
+ const [owner, repo, commit, area, slug, filename] = rawSegments.slice(1);
92
+ if (`${owner}/${repo}` !== REGISTRY_REPOSITORY) {
93
+ throw new Error("registry URL repository is not approved");
94
+ }
95
+ if (!FULL_COMMIT_SHA_RE.test(commit)) {
96
+ throw new Error("registry URL must contain a full lowercase commit SHA");
97
+ }
98
+ if (
99
+ area !== expected.area ||
100
+ slug !== expected.slug ||
101
+ filename !== expected.filename
102
+ ) {
103
+ throw new Error(
104
+ "registry URL identity does not match the requested integration",
105
+ );
106
+ }
107
+ const canonical = registryRawUrl(
108
+ commit,
109
+ expected.area,
110
+ expected.slug,
111
+ expected.filename,
112
+ );
113
+ if (value !== canonical) {
114
+ throw new Error("registry URL is not canonical");
115
+ }
116
+
117
+ return { commit, area: expected.area, slug, filename: expected.filename };
118
+ };