@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,28 @@
1
+ /**
2
+ * Runtime-agnostic base64 decoder that returns raw bytes.
3
+ */
4
+ export const base64ToBytes = (b64: string): Uint8Array => {
5
+ const binary = atob(b64);
6
+ const bytes = new Uint8Array(binary.length);
7
+
8
+ for (let i = 0; i < binary.length; i += 1) {
9
+ bytes[i] = binary.charCodeAt(i);
10
+ }
11
+
12
+ return bytes;
13
+ };
14
+
15
+ /**
16
+ * Normalize a content-type header value to its media type token.
17
+ */
18
+ export const normalizeContentType = (
19
+ raw: string | null | undefined,
20
+ fallback: string,
21
+ ): string => {
22
+ if (raw === null || raw === undefined) {
23
+ return fallback;
24
+ }
25
+
26
+ const normalized = raw.split(";", 1)[0].trim().toLowerCase();
27
+ return normalized === "" ? fallback : normalized;
28
+ };
@@ -0,0 +1,357 @@
1
+ import { Schema as S } from "effect";
2
+ import { parseVideoGenerationInput } from "./videos";
3
+
4
+ /**
5
+ * Metadata-only media-default selection contract. Used by the cloud
6
+ * resolver and the daemon's local-first plan fetch. Never carries
7
+ * prompts, images, audio bytes, or speech text.
8
+ */
9
+
10
+ export const MediaDefaultSurface = S.Literals([
11
+ "image",
12
+ "image_edit",
13
+ "transcription",
14
+ "speech",
15
+ "video",
16
+ "embeddings",
17
+ ]);
18
+ export type TMediaDefaultSurface = S.Schema.Type<typeof MediaDefaultSurface>;
19
+
20
+ /**
21
+ * Bounded audio encodings the default selector may match against
22
+ * catalog `audio_support.input_formats`. `unknown` means the caller
23
+ * did not positively prove a compatible encoding — restricted
24
+ * subscription models must not be assumed compatible.
25
+ */
26
+ export const MediaAudioInputFormat = S.Literals([
27
+ "pcm_s16le_16khz_mono",
28
+ "wav_pcm16_16khz_mono",
29
+ "webm_opus",
30
+ "unknown",
31
+ ]);
32
+ export type TMediaAudioInputFormat = S.Schema.Type<
33
+ typeof MediaAudioInputFormat
34
+ >;
35
+
36
+ export const MEDIA_DEFAULT_CONSTRAINT_STRING_MAX = 64;
37
+ export const MEDIA_DEFAULT_PLAN_JSON_MAX_BYTES = 2048;
38
+
39
+ const BoundedConstraintString = S.String.check(
40
+ S.isMinLength(1),
41
+ S.isMaxLength(MEDIA_DEFAULT_CONSTRAINT_STRING_MAX),
42
+ );
43
+
44
+ export const MediaDefaultConstraints = S.Struct({
45
+ input_format: S.optional(MediaAudioInputFormat),
46
+ voice: S.optional(BoundedConstraintString),
47
+ response_format: S.optional(BoundedConstraintString),
48
+ size: S.optional(BoundedConstraintString),
49
+ quality: S.optional(BoundedConstraintString),
50
+ seconds: S.optional(BoundedConstraintString),
51
+ });
52
+ export type TMediaDefaultConstraints = S.Schema.Type<
53
+ typeof MediaDefaultConstraints
54
+ >;
55
+
56
+ export const MediaDefaultRequest = S.Struct({
57
+ surface: MediaDefaultSurface,
58
+ constraints: S.optional(MediaDefaultConstraints),
59
+ });
60
+ export type TMediaDefaultRequest = S.Schema.Type<typeof MediaDefaultRequest>;
61
+
62
+ export const MEDIA_DEFAULT_PLAN_QUERY_KEY = "media_default";
63
+
64
+ const decodeConstraints = S.decodeUnknownResult(MediaDefaultConstraints);
65
+ const decodeRequest = S.decodeUnknownResult(MediaDefaultRequest);
66
+
67
+ const utf8ByteLength = (value: string): number =>
68
+ new TextEncoder().encode(value).byteLength;
69
+
70
+ const looksLikeWav = (bytes: Uint8Array): boolean =>
71
+ bytes.length >= 12 &&
72
+ bytes[0] === 0x52 &&
73
+ bytes[1] === 0x49 &&
74
+ bytes[2] === 0x46 &&
75
+ bytes[3] === 0x46 &&
76
+ bytes[8] === 0x57 &&
77
+ bytes[9] === 0x41 &&
78
+ bytes[10] === 0x56 &&
79
+ bytes[11] === 0x45;
80
+
81
+ const asciiAt = (view: DataView, offset: number, len: number): string => {
82
+ let out = "";
83
+ for (let i = 0; i < len; i++)
84
+ out += String.fromCharCode(view.getUint8(offset + i));
85
+ return out;
86
+ };
87
+
88
+ const containsAscii = (
89
+ bytes: Uint8Array,
90
+ needle: string,
91
+ maxBytes = 8192,
92
+ ): boolean => {
93
+ const limit = Math.min(bytes.length, maxBytes);
94
+ const n = needle.length;
95
+ if (n === 0 || n > limit) return false;
96
+ outer: for (let i = 0; i <= limit - n; i++) {
97
+ for (let j = 0; j < n; j++) {
98
+ if (bytes[i + j] !== needle.charCodeAt(j)) continue outer;
99
+ }
100
+ return true;
101
+ }
102
+ return false;
103
+ };
104
+
105
+ /** Strict PCM16 16 kHz mono WAV: bounded chunks, fmt size >= 16, data present. */
106
+ const wavIsPcm16kMono16 = (bytes: Uint8Array): boolean => {
107
+ if (!looksLikeWav(bytes)) return false;
108
+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
109
+ const riffSize = view.getUint32(4, true);
110
+ if (riffSize + 8 > bytes.length) return false;
111
+ let offset = 12;
112
+ let formatTag: number | null = null;
113
+ let channels: number | null = null;
114
+ let sampleRate: number | null = null;
115
+ let byteRate: number | null = null;
116
+ let blockAlign: number | null = null;
117
+ let bitsPerSample: number | null = null;
118
+ let hasData = false;
119
+ while (offset + 8 <= bytes.length) {
120
+ const chunkId = asciiAt(view, offset, 4);
121
+ const chunkSize = view.getUint32(offset + 4, true);
122
+ const bodyStart = offset + 8;
123
+ if (bodyStart > bytes.length) return false;
124
+ if (chunkSize > bytes.length - bodyStart) return false;
125
+ if (chunkId === "fmt ") {
126
+ if (chunkSize < 16) return false;
127
+ formatTag = view.getUint16(bodyStart, true);
128
+ channels = view.getUint16(bodyStart + 2, true);
129
+ sampleRate = view.getUint32(bodyStart + 4, true);
130
+ byteRate = view.getUint32(bodyStart + 8, true);
131
+ blockAlign = view.getUint16(bodyStart + 12, true);
132
+ bitsPerSample = view.getUint16(bodyStart + 14, true);
133
+ } else if (chunkId === "data") {
134
+ if (chunkSize === 0) return false;
135
+ hasData = true;
136
+ }
137
+ offset = bodyStart + chunkSize + (chunkSize % 2);
138
+ }
139
+ if (
140
+ formatTag !== 1 ||
141
+ channels !== 1 ||
142
+ sampleRate !== 16_000 ||
143
+ bitsPerSample !== 16 ||
144
+ !hasData
145
+ ) {
146
+ return false;
147
+ }
148
+ const expectedAlign = (channels * bitsPerSample) / 8;
149
+ const expectedRate = sampleRate * expectedAlign;
150
+ return blockAlign === expectedAlign && byteRate === expectedRate;
151
+ };
152
+
153
+ const looksLikeWebm = (bytes: Uint8Array): boolean =>
154
+ bytes.length >= 4 &&
155
+ bytes[0] === 0x1a &&
156
+ bytes[1] === 0x45 &&
157
+ bytes[2] === 0xdf &&
158
+ bytes[3] === 0xa3;
159
+
160
+ const parseContentTypeParams = (
161
+ contentType: string | undefined,
162
+ ): { readonly type: string; readonly params: Record<string, string> } => {
163
+ if (contentType === undefined || contentType.length === 0) {
164
+ return { type: "", params: {} };
165
+ }
166
+ const parts = contentType.split(";").map((p) => p.trim().toLowerCase());
167
+ const type = parts[0] ?? "";
168
+ const params: Record<string, string> = {};
169
+ for (const part of parts.slice(1)) {
170
+ const eq = part.indexOf("=");
171
+ if (eq <= 0) continue;
172
+ const key = part.slice(0, eq).trim();
173
+ let value = part.slice(eq + 1).trim();
174
+ if (
175
+ (value.startsWith('"') && value.endsWith('"')) ||
176
+ (value.startsWith("'") && value.endsWith("'"))
177
+ ) {
178
+ value = value.slice(1, -1);
179
+ }
180
+ params[key] = value;
181
+ }
182
+ return { type, params };
183
+ };
184
+
185
+ const declaredLittleEndianPcm16kMono = (contentType?: string): boolean => {
186
+ const { type, params } = parseContentTypeParams(contentType);
187
+ if (type === "audio/l16" || type.endsWith("/l16")) return false;
188
+ if (type !== "audio/pcm" && !type.endsWith("/pcm")) return false;
189
+ const rate = params.rate ?? params.samplerate;
190
+ const channels = params.channels;
191
+ const bits = params.bits ?? params.bitspersample;
192
+ const endian = params.endian ?? params.endianness;
193
+ return (
194
+ rate === "16000" &&
195
+ channels === "1" &&
196
+ bits === "16" &&
197
+ (endian === "little" || endian === "le" || endian === "little-endian")
198
+ );
199
+ };
200
+
201
+ const codecsIndicateOpus = (codecs: string | undefined): boolean => {
202
+ if (codecs === undefined || codecs.length === 0) return false;
203
+ const tokens = codecs
204
+ .toLowerCase()
205
+ .split(/[\s,]+/)
206
+ .filter((t) => t.length > 0);
207
+ if (tokens.some((t) => t === "vorbis")) return false;
208
+ return tokens.some((t) => t === "opus");
209
+ };
210
+
211
+ const bytesAreWebmOpus = (bytes: Uint8Array): boolean => {
212
+ if (!looksLikeWebm(bytes) && !containsAscii(bytes, "webm")) return false;
213
+ if (containsAscii(bytes, "A_VORBIS") || containsAscii(bytes, "vorbis")) {
214
+ return false;
215
+ }
216
+ return containsAscii(bytes, "A_OPUS") || containsAscii(bytes, "OpusHead");
217
+ };
218
+
219
+ export type TMediaAudioInspectInput = {
220
+ readonly bytes?: Uint8Array;
221
+ readonly contentType?: string;
222
+ readonly filename?: string;
223
+ /** Positive encoding claim from a trusted parser — never inferred from .pcm/.raw. */
224
+ readonly encoding?: TMediaAudioInputFormat;
225
+ };
226
+
227
+ /**
228
+ * Classify caller audio for compatibility matching. Extensions and
229
+ * generic PCM/L16 MIME types are not encodings.
230
+ */
231
+ export const inspectMediaAudioInputFormat = (
232
+ input: TMediaAudioInspectInput,
233
+ ): TMediaAudioInputFormat => {
234
+ if (
235
+ input.encoding === "pcm_s16le_16khz_mono" ||
236
+ input.encoding === "wav_pcm16_16khz_mono" ||
237
+ input.encoding === "webm_opus"
238
+ ) {
239
+ return input.encoding;
240
+ }
241
+ if (input.bytes !== undefined && wavIsPcm16kMono16(input.bytes)) {
242
+ return "wav_pcm16_16khz_mono";
243
+ }
244
+ if (input.bytes !== undefined && looksLikeWav(input.bytes)) {
245
+ return "unknown";
246
+ }
247
+ const { type, params } = parseContentTypeParams(input.contentType);
248
+ const webmType = type.includes("webm");
249
+ if (codecsIndicateOpus(params.codecs) && webmType) return "webm_opus";
250
+ if (input.bytes !== undefined && bytesAreWebmOpus(input.bytes)) {
251
+ return "webm_opus";
252
+ }
253
+ if (declaredLittleEndianPcm16kMono(input.contentType)) {
254
+ return "pcm_s16le_16khz_mono";
255
+ }
256
+ return "unknown";
257
+ };
258
+
259
+ const pickConstraints = (
260
+ rec: Record<string, unknown>,
261
+ audio?: TMediaAudioInspectInput,
262
+ ): TMediaDefaultConstraints | "invalid" | undefined => {
263
+ const parsed = decodeConstraints({
264
+ ...(rec.voice !== undefined ? { voice: rec.voice } : {}),
265
+ ...(rec.response_format !== undefined
266
+ ? { response_format: rec.response_format }
267
+ : {}),
268
+ ...(rec.size !== undefined ? { size: rec.size } : {}),
269
+ ...(rec.quality !== undefined ? { quality: rec.quality } : {}),
270
+ ...(rec.seconds !== undefined ? { seconds: rec.seconds } : {}),
271
+ ...(audio !== undefined
272
+ ? { input_format: inspectMediaAudioInputFormat(audio) }
273
+ : rec.input_format !== undefined
274
+ ? { input_format: rec.input_format }
275
+ : {}),
276
+ });
277
+ if (parsed._tag === "Failure") return "invalid";
278
+ const value = parsed.success;
279
+ return Object.keys(value).length > 0 ? value : undefined;
280
+ };
281
+
282
+ export const sanitizeMediaDefaultConstraints = (
283
+ surface: TMediaDefaultSurface,
284
+ body: unknown,
285
+ audio?: TMediaAudioInspectInput,
286
+ ): TMediaDefaultConstraints | undefined => {
287
+ const result = mediaDefaultRequestFromBody(surface, body, audio);
288
+ return result === null ? undefined : result.constraints;
289
+ };
290
+
291
+ export const mediaDefaultRequestFromBody = (
292
+ surface: TMediaDefaultSurface,
293
+ body: unknown,
294
+ audio?: TMediaAudioInspectInput,
295
+ ): TMediaDefaultRequest | null => {
296
+ if (surface === "video") {
297
+ try {
298
+ const input = parseVideoGenerationInput(body);
299
+ const constraints = pickConstraints(input);
300
+ if (constraints === "invalid") return null;
301
+ return {
302
+ surface,
303
+ ...(constraints === undefined ? {} : { constraints }),
304
+ };
305
+ } catch {
306
+ return null;
307
+ }
308
+ }
309
+ const audioForSurface = surface === "transcription" ? audio : undefined;
310
+ if (body !== null && typeof body === "object" && !Array.isArray(body)) {
311
+ const constraints = pickConstraints(
312
+ body as Record<string, unknown>,
313
+ audioForSurface,
314
+ );
315
+ if (constraints === "invalid") return null;
316
+ const request: TMediaDefaultRequest =
317
+ constraints === undefined ? { surface } : { surface, constraints };
318
+ return decodeRequest(request)._tag === "Success" ? request : null;
319
+ }
320
+ if (audioForSurface !== undefined) {
321
+ const constraints = pickConstraints({}, audioForSurface);
322
+ if (constraints === "invalid") return null;
323
+ const request: TMediaDefaultRequest =
324
+ constraints === undefined ? { surface } : { surface, constraints };
325
+ return decodeRequest(request)._tag === "Success" ? request : null;
326
+ }
327
+ return { surface };
328
+ };
329
+
330
+ export const encodeMediaDefaultPlanQuery = (
331
+ request: TMediaDefaultRequest,
332
+ ): string | null => {
333
+ const decoded = decodeRequest(request);
334
+ if (decoded._tag === "Failure") return null;
335
+ const json = JSON.stringify(decoded.success);
336
+ if (utf8ByteLength(json) > MEDIA_DEFAULT_PLAN_JSON_MAX_BYTES) return null;
337
+ return `${MEDIA_DEFAULT_PLAN_QUERY_KEY}=${encodeURIComponent(json)}`;
338
+ };
339
+
340
+ export const decodeMediaDefaultPlanQuery = (
341
+ params: URLSearchParams,
342
+ ): TMediaDefaultRequest | null => {
343
+ const raw = params.get(MEDIA_DEFAULT_PLAN_QUERY_KEY);
344
+ if (raw === null || raw.length === 0) return null;
345
+ if (utf8ByteLength(raw) > MEDIA_DEFAULT_PLAN_JSON_MAX_BYTES) return null;
346
+ let parsed: unknown;
347
+ try {
348
+ parsed = JSON.parse(raw);
349
+ } catch {
350
+ return null;
351
+ }
352
+ const decoded = decodeRequest(parsed);
353
+ if (decoded._tag === "Failure") return null;
354
+ const json = JSON.stringify(decoded.success);
355
+ if (utf8ByteLength(json) > MEDIA_DEFAULT_PLAN_JSON_MAX_BYTES) return null;
356
+ return decoded.success;
357
+ };
@@ -0,0 +1,132 @@
1
+ /**
2
+ * Generic media-dimension arithmetic and accepted-set helpers.
3
+ *
4
+ * This module is deliberately FACT-FREE. It holds no provider's
5
+ * durations, ratios, resolution tiers or counts — those are catalog-
6
+ * owned data on a model card (`ModelCaps.media*`), because they drift
7
+ * with a vendor's fleet and a constant here would silently apply a
8
+ * today-model's limits to tomorrow's. What lives here is only the
9
+ * arithmetic every media lane would otherwise re-implement: parsing a
10
+ * `WIDTHxHEIGHT` size, reducing it to a ratio, labelling its short
11
+ * edge, matching it against a declared vocabulary, and rendering an
12
+ * accepted set for an error message.
13
+ *
14
+ * The request SHAPE (which JSON field carries image bytes, how
15
+ * instances/parameters nest) stays in the protocol wire schemas — that
16
+ * is structure, not a per-model fact.
17
+ *
18
+ * Consumers take the VALUE SETS from resolved caps and pass them in. A
19
+ * set that is absent means UNKNOWN: the value is forwarded and the
20
+ * provider's own error is the authority. Nothing here clamps or
21
+ * rewrites a caller's request.
22
+ */
23
+
24
+ /** Parsed `WIDTHxHEIGHT` dimensions. */
25
+ export type TMediaDimensions = {
26
+ readonly width: number;
27
+ readonly height: number;
28
+ };
29
+
30
+ /** One documented resolution tier: a name and its published long edge. */
31
+ export type TMediaResolutionTier = {
32
+ readonly resolution: string;
33
+ readonly longEdge: number;
34
+ };
35
+
36
+ /** Parse a canonical `WIDTHxHEIGHT` size; null when it is not that shape. */
37
+ export const parseMediaDimensions = (size: string): TMediaDimensions | null => {
38
+ const match = /^(\d+)x(\d+)$/.exec(size);
39
+ if (match === null) return null;
40
+ const width = Number(match[1]);
41
+ const height = Number(match[2]);
42
+ if (
43
+ !Number.isSafeInteger(width) ||
44
+ !Number.isSafeInteger(height) ||
45
+ width <= 0 ||
46
+ height <= 0
47
+ )
48
+ return null;
49
+ return { width, height };
50
+ };
51
+
52
+ const gcd = (a: number, b: number): number => (b === 0 ? a : gcd(b, a % b));
53
+
54
+ /** Reduce dimensions to their `W:H` ratio (1280x720 → "16:9"). */
55
+ export const aspectRatioFromDimensions = (
56
+ dimensions: TMediaDimensions,
57
+ ): string => {
58
+ const divisor = gcd(dimensions.width, dimensions.height);
59
+ return `${dimensions.width / divisor}:${dimensions.height / divisor}`;
60
+ };
61
+
62
+ /** Short-edge resolution label (720x1280 → "720p"; 3840x2160 → "4k"). */
63
+ export const resolutionFromDimensions = (
64
+ dimensions: TMediaDimensions,
65
+ ): string => {
66
+ const shortEdge = Math.min(dimensions.width, dimensions.height);
67
+ return shortEdge === 2160 ? "4k" : `${shortEdge}p`;
68
+ };
69
+
70
+ /**
71
+ * Match dimensions against a provider's DECLARED aspect-ratio
72
+ * vocabulary by value, and return the provider's own spelling.
73
+ *
74
+ * A vendor may publish non-integer ratios (`9:19.5`), which a gcd
75
+ * reduction can never produce: 1080x2340 reduces to `6:13`, the same
76
+ * ratio as a declared `9:19.5`. Comparing numerically keeps the
77
+ * caller's framing instead of refusing an aspect the provider accepts.
78
+ */
79
+ export const matchDeclaredAspectRatio = (
80
+ allowed: ReadonlyArray<string>,
81
+ dimensions: TMediaDimensions,
82
+ ): string | null => {
83
+ const requested = dimensions.width / dimensions.height;
84
+ for (const declared of allowed) {
85
+ const [width, height] = declared.split(":").map(Number);
86
+ if (
87
+ width === undefined ||
88
+ height === undefined ||
89
+ !Number.isFinite(width) ||
90
+ !Number.isFinite(height) ||
91
+ height === 0
92
+ )
93
+ continue;
94
+ // Tolerance covers the rounding in published one-decimal ratios.
95
+ if (Math.abs(width / height - requested) <= 1e-3) return declared;
96
+ }
97
+ return null;
98
+ };
99
+
100
+ /**
101
+ * The tier whose documented long edge the request matches EXACTLY.
102
+ *
103
+ * Deliberately not a nearest/covering heuristic: "smallest tier that
104
+ * covers it" promotes a size to a pricier tier and demotes another into
105
+ * an upscale, neither of which the caller asked for. A long edge with no
106
+ * documented tier returns null so the adapter can say so by name.
107
+ */
108
+ export const resolutionTierForLongEdge = (
109
+ tiers: ReadonlyArray<TMediaResolutionTier>,
110
+ longEdge: number,
111
+ allowed?: ReadonlyArray<string>,
112
+ ): string | null =>
113
+ tiers.find(
114
+ (tier) =>
115
+ longEdge === tier.longEdge &&
116
+ (allowed === undefined || allowed.includes(tier.resolution)),
117
+ )?.resolution ?? null;
118
+
119
+ /**
120
+ * Membership against a declared set. An UNDEFINED set means the catalog
121
+ * knows nothing about this model, so the value passes through — only a
122
+ * present set can refuse.
123
+ */
124
+ export const isAllowedMediaOption = (
125
+ allowed: ReadonlyArray<string> | undefined,
126
+ value: string,
127
+ ): boolean => allowed === undefined || allowed.includes(value);
128
+
129
+ /** Render an allowed set for a corrective, non-clamping error message. */
130
+ export const describeAllowed = (
131
+ allowed: ReadonlyArray<string | number>,
132
+ ): string => allowed.map((value) => String(value)).join(", ");
@@ -0,0 +1,61 @@
1
+ import { Option, Schema as S, SchemaGetter } from "effect";
2
+
3
+ /**
4
+ * v3 `optionalToOptional` dropped blank values by returning `Option.none`.
5
+ * `decodeTo` preserves that behaviour: an absent key, `undefined`, or a
6
+ * whitespace-only string is omitted, while a nonempty ID is preserved exactly.
7
+ */
8
+ /** Public selection input only; concrete provider requests still require a model. */
9
+ const optionalMediaModelDescription =
10
+ "Optional model ID. Omit for automatic default-chain selection; never send an empty-string placeholder. Preserve an explicitly selected nonempty ID exactly.";
11
+
12
+ /**
13
+ * The wire representation is an exact optional string: `undefined` cannot
14
+ * occur in JSON, so documenting it as `null` would invite invalid requests.
15
+ */
16
+ export const OptionalMediaModel = S.optionalKey(S.String).pipe(
17
+ S.decodeTo(S.optionalKey(S.String), {
18
+ decode: SchemaGetter.transformOptional(
19
+ (value: Option.Option<string>): Option.Option<string> =>
20
+ Option.filter(value, (model): model is string => model.trim() !== ""),
21
+ ),
22
+ encode: SchemaGetter.transformOptional(
23
+ (value: Option.Option<string>): Option.Option<string> => value,
24
+ ),
25
+ }),
26
+ S.annotateEncoded({ description: optionalMediaModelDescription }),
27
+ );
28
+ export const MediaModelSelection = S.Struct({ model: OptionalMediaModel });
29
+ const decodeMediaModelSelectionSchema =
30
+ S.decodeUnknownSync(MediaModelSelection);
31
+
32
+ /**
33
+ * JavaScript callers can pass `undefined` even though it has no JSON wire
34
+ * representation. Normalize it to an omitted optional key before validation.
35
+ */
36
+ export const decodeMediaModelSelection = (input: {
37
+ readonly model?: unknown;
38
+ }): { readonly model?: string } =>
39
+ input.model === undefined ? {} : decodeMediaModelSelectionSchema(input);
40
+
41
+ const VideoReferenceList = S.Array(S.String.check(S.isMinLength(1)));
42
+ /** Empty reference lists carry no guidance; invalid entries and wrong types still fail. */
43
+ export const OptionalVideoReferences = S.optionalKey(VideoReferenceList).pipe(
44
+ S.decodeTo(S.optionalKey(VideoReferenceList), {
45
+ decode: SchemaGetter.transformOptional(
46
+ (
47
+ value: Option.Option<readonly string[]>,
48
+ ): Option.Option<readonly string[]> =>
49
+ Option.filter(
50
+ value,
51
+ (references): references is readonly string[] =>
52
+ references.length > 0,
53
+ ),
54
+ ),
55
+ encode: SchemaGetter.transformOptional(
56
+ (
57
+ value: Option.Option<readonly string[]>,
58
+ ): Option.Option<readonly string[]> => value,
59
+ ),
60
+ }),
61
+ );