@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,14 @@
1
+ import { Schema as S } from "effect";
2
+
3
+ export const ErrorBody = S.Struct({
4
+ message: S.String,
5
+ type: S.String,
6
+ code: S.optional(S.String),
7
+ param: S.optional(S.NullOr(S.String)),
8
+ });
9
+ export type TErrorBody = S.Schema.Type<typeof ErrorBody>;
10
+
11
+ export const ErrorEnvelope = S.Struct({
12
+ error: ErrorBody,
13
+ });
14
+ export type TErrorEnvelope = S.Schema.Type<typeof ErrorEnvelope>;
@@ -0,0 +1,141 @@
1
+ /**
2
+ * Named execution variants and composable capture — public wire vocabulary.
3
+ *
4
+ * Distinct, provider-unprefixed integration ids. `ACTIVE_SUB_METHOD` is the
5
+ * ONLY selector (global + `provider:method` override grammar); this module
6
+ * defines its token vocabulary and the typed wire shapes it carries.
7
+ *
8
+ * See `docs/plan/bridge-variants-and-capture-adapters/00-requirements.md`
9
+ * and `09-implementation-plan.md` §4 for the approved naming baseline and
10
+ * selection model. `12-hermes-adoption-plan.md` is the reference for the
11
+ * planned `sdk-facade` implementation — NOT built here; this module only
12
+ * reserves its wire vocabulary.
13
+ *
14
+ * - `stream-json` — Claude direct CLI (stream-json protocol)
15
+ * - `agent-sdk` — official Claude Agent SDK, if independently selectable
16
+ * (reserved; no `-capture` form is defined for it in this baseline)
17
+ * - `sdk-facade` — planned Hermes-inspired Claude completion facade
18
+ * - `acp` — Cursor and future ACP-protocol providers
19
+ * - `app-server` — Codex
20
+ * - `msp` — Muse
21
+ * - `handrolled` — hand-rolled execution (never vendor-controlled, so it
22
+ * never carries `-capture`)
23
+ */
24
+
25
+ import { Schema as S } from "effect";
26
+
27
+ /**
28
+ * Stable, provider-unprefixed integration ids — the specific vendor-
29
+ * controlled integration API a hop drives, not a generic "CLI"/"SDK"
30
+ * bucket. Closed: a new variant is a deliberate, reviewable schema change.
31
+ */
32
+ export const BridgeVariant = S.Literals([
33
+ "stream-json",
34
+ "agent-sdk",
35
+ "sdk-facade",
36
+ "acp",
37
+ "app-server",
38
+ "msp",
39
+ ]);
40
+ export type TBridgeVariant = S.Schema.Type<typeof BridgeVariant>;
41
+
42
+ /**
43
+ * Every registered {@link TBridgeVariant}, for enumeration/tests. Order
44
+ * matches the naming baseline in 00-requirements.md.
45
+ */
46
+ export const BRIDGE_VARIANTS: ReadonlyArray<TBridgeVariant> =
47
+ BridgeVariant.literals;
48
+
49
+ export const isBridgeVariant = (value: string): value is TBridgeVariant =>
50
+ (BridgeVariant.literals as ReadonlyArray<string>).includes(value);
51
+
52
+ /**
53
+ * Which variants have a defined `<variant>-capture` form. Per the approved
54
+ * naming baseline, every variant has one EXCEPT `agent-sdk` — it is
55
+ * reserved for the official Agent SDK as an independently selectable
56
+ * integration, and no capture form for it is part of this baseline. A
57
+ * capture form existing here means the NAME is grammatically valid; it is
58
+ * NOT a claim that any given provider's binding is capture-ready (that is
59
+ * the provider execution registry's job — see
60
+ * `packages/cli/daemon/src/execution-registry.ts`).
61
+ */
62
+ export const BRIDGE_VARIANTS_WITH_CAPTURE_FORM: ReadonlySet<TBridgeVariant> =
63
+ new Set(["stream-json", "sdk-facade", "acp", "app-server", "msp"]);
64
+
65
+ export const bridgeVariantSupportsCaptureForm = (
66
+ variant: TBridgeVariant,
67
+ ): boolean => BRIDGE_VARIANTS_WITH_CAPTURE_FORM.has(variant);
68
+
69
+ /**
70
+ * A concrete, resolved execution selection: either `handrolled` (never
71
+ * vendor-controlled, so it structurally has no `variant`/`capture` fields
72
+ * and `handrolled-capture` cannot be represented) or a bridge variant with
73
+ * its capture flag.
74
+ */
75
+ export const ExecutionSelectionHandrolled = S.Struct({
76
+ kind: S.Literal("handrolled"),
77
+ });
78
+ export const ExecutionSelectionBridge = S.Struct({
79
+ kind: S.Literal("bridge"),
80
+ variant: BridgeVariant,
81
+ capture: S.Boolean,
82
+ });
83
+ export const ExecutionSelection = S.Union([
84
+ ExecutionSelectionHandrolled,
85
+ ExecutionSelectionBridge,
86
+ ]);
87
+ export type TExecutionSelection = S.Schema.Type<typeof ExecutionSelection>;
88
+
89
+ export const executionSelectionHandrolled = (): TExecutionSelection => ({
90
+ kind: "handrolled",
91
+ });
92
+
93
+ export const executionSelectionBridge = (
94
+ variant: TBridgeVariant,
95
+ capture: boolean,
96
+ ): TExecutionSelection => ({ kind: "bridge", variant, capture });
97
+
98
+ const CAPTURE_SUFFIX = "-capture";
99
+
100
+ /**
101
+ * Parse one `ACTIVE_SUB_METHOD` token (a bare method, not a
102
+ * `provider:method` pair — callers split that first): `handrolled` or any
103
+ * `<variant>`/`<variant>-capture` combination that
104
+ * {@link bridgeVariantSupportsCaptureForm} allows. Returns `null` for
105
+ * anything else, INCLUDING `handrolled-capture` — capture requires
106
+ * vendor-controlled execution, which `handrolled` by definition is not, so
107
+ * it is excluded structurally here rather than merely rejected downstream.
108
+ * Case-sensitive lowercase only, matching the existing `ACTIVE_SUB_METHOD`
109
+ * convention.
110
+ */
111
+ export const parseActiveExecutionToken = (
112
+ token: string,
113
+ ): TExecutionSelection | null => {
114
+ if (token === "handrolled") return executionSelectionHandrolled();
115
+ const capture = token.endsWith(CAPTURE_SUFFIX);
116
+ const base = capture ? token.slice(0, -CAPTURE_SUFFIX.length) : token;
117
+ if (base.length === 0 || !isBridgeVariant(base)) return null;
118
+ if (capture && !bridgeVariantSupportsCaptureForm(base)) return null;
119
+ return executionSelectionBridge(base, capture);
120
+ };
121
+
122
+ /** Inverse of {@link parseActiveExecutionToken} — for diagnostics/logging. */
123
+ export const formatActiveExecutionToken = (
124
+ token: TExecutionSelection,
125
+ ): string => {
126
+ if (token.kind === "handrolled") return "handrolled";
127
+ return token.capture ? `${token.variant}${CAPTURE_SUFFIX}` : token.variant;
128
+ };
129
+
130
+ /**
131
+ * Every valid public token, for enumeration/tests.
132
+ * `handrolled-capture` is deliberately absent — it is never valid.
133
+ */
134
+ export const ACTIVE_EXECUTION_TOKENS: ReadonlyArray<string> = [
135
+ "handrolled",
136
+ ...BRIDGE_VARIANTS.flatMap((variant) =>
137
+ bridgeVariantSupportsCaptureForm(variant)
138
+ ? [variant, `${variant}${CAPTURE_SUFFIX}`]
139
+ : [variant],
140
+ ),
141
+ ];
@@ -0,0 +1,33 @@
1
+ import { Schema as S } from "effect";
2
+
3
+ /** Header carrying an origin-authorized single device hop. */
4
+ export const HOP_GRANT_HEADER = "x-openllm-hop-grant";
5
+
6
+ /** Upper bound on an encoded hop grant on the wire (payload + signature). */
7
+ export const HOP_GRANT_B64_MAX = 2048;
8
+
9
+ /**
10
+ * Daemon capability header. A daemon sends it on every plan fetch; the cloud
11
+ * refuses capped plans and hop-grant redemption without it
12
+ * (`daemon_outdated`), so a daemon that can't report holds never serves a
13
+ * capped key uncapped.
14
+ */
15
+ export const DAEMON_CAPS_HEADER = "x-openllm-daemon-caps";
16
+ export const DAEMON_CAPS_HOLDS = "holds-v2";
17
+
18
+ /**
19
+ * Short-lived authorization for one model and its consumer-key hold, for ONE
20
+ * device: only `device_key_id` may redeem it, and only that key may then
21
+ * report the hold's usage.
22
+ */
23
+ export const HopGrant = S.Struct({
24
+ v: S.Literal(1),
25
+ user_id: S.String,
26
+ key_id: S.String,
27
+ device_key_id: S.String,
28
+ model: S.String,
29
+ nonce: S.String,
30
+ exp: S.Number,
31
+ });
32
+
33
+ export type THopGrant = S.Schema.Type<typeof HopGrant>;
@@ -0,0 +1,263 @@
1
+ import * as Result from "effect/Result";
2
+ import type {
3
+ TImageEditParseFailure,
4
+ TImageEditParseResult,
5
+ TImageEditRequest,
6
+ } from "./images";
7
+ import { decodeImageEditRequest, IMAGE_EDIT_MAX_BODY_BYTES } from "./images";
8
+
9
+ const asRecord = (value: unknown): Record<string, unknown> | null => {
10
+ if (value === null || typeof value !== "object" || Array.isArray(value)) {
11
+ return null;
12
+ }
13
+ return value as Record<string, unknown>;
14
+ };
15
+
16
+ const fail = (
17
+ code: TImageEditParseFailure["code"],
18
+ message: string,
19
+ ): TImageEditParseResult => ({ ok: false, error: { code, message } });
20
+
21
+ const isPresent = (value: unknown): boolean => {
22
+ if (value === undefined || value === null) return false;
23
+ if (typeof value === "string" && value.trim() === "") return false;
24
+ return true;
25
+ };
26
+
27
+ const referenceCount = (body: Record<string, unknown>): number => {
28
+ let count = 0;
29
+ if (isPresent(body.image)) {
30
+ if (Array.isArray(body.image)) count += body.image.length;
31
+ else count += 1;
32
+ }
33
+ if (Array.isArray(body.images)) count += body.images.length;
34
+ return count;
35
+ };
36
+
37
+ // Strict `data:[<mime>][;charset=<x>];base64,<payload>` matcher. The base64
38
+ // group is validated for charset AND padding shape (0-2 trailing `=`, only at
39
+ // the end) — a loose regex would let a malformed/truncated payload through to
40
+ // byte-size math that silently under-counts it.
41
+ const DATA_URL_PATTERN =
42
+ /^data:([-\w.+]+\/[-\w.+]+)?(;charset=[-\w]+)?;base64,([A-Za-z0-9+/]*={0,2})$/;
43
+
44
+ /**
45
+ * Estimate the decoded byte size of a `data:` URL from its base64 payload
46
+ * length, without decoding it. Non-data URLs (a remote `https://` reference)
47
+ * return 0 — there is no local byte estimate to make; a fetched remote
48
+ * reference is bounded when it actually transits the tunnel
49
+ * (`TUNNEL_MEDIA_MAX_BODY_BYTES`), not here. A `data:` URL that fails the
50
+ * strict base64 shape returns `null` so the caller rejects it explicitly
51
+ * instead of silently under-counting a malformed payload.
52
+ */
53
+ const estimateDataUrlBytes = (url: string): number | null => {
54
+ if (!url.startsWith("data:")) return 0;
55
+ const match = DATA_URL_PATTERN.exec(url);
56
+ if (match === null) return null;
57
+ const base64 = match[3] ?? "";
58
+ if (base64.length === 0 || base64.length % 4 !== 0) return null;
59
+ const padding = base64.endsWith("==") ? 2 : base64.endsWith("=") ? 1 : 0;
60
+ return (base64.length / 4) * 3 - padding;
61
+ };
62
+
63
+ const referenceUrl = (body: Record<string, unknown>): string | null => {
64
+ const image = body.image;
65
+ if (typeof image === "string" && image.length > 0) return image;
66
+ const imageObj = asRecord(image);
67
+ if (imageObj !== null) {
68
+ if (typeof imageObj.url === "string") return imageObj.url;
69
+ if (typeof imageObj.image_url === "string") return imageObj.image_url;
70
+ }
71
+ const images = body.images;
72
+ if (Array.isArray(images) && images.length === 1) {
73
+ const first = asRecord(images[0]);
74
+ if (first !== null) {
75
+ if (typeof first.image_url === "string") return first.image_url;
76
+ if (typeof first.url === "string") return first.url;
77
+ }
78
+ if (typeof images[0] === "string") return images[0];
79
+ }
80
+ return null;
81
+ };
82
+
83
+ /**
84
+ * Normalize documented multipart fields and a narrow JSON convenience into
85
+ * the canonical single-image {@link TImageEditRequest}. Masks and extra
86
+ * references fail explicitly — they are never dropped.
87
+ */
88
+ export const parseImageEditInput = (raw: unknown): TImageEditParseResult => {
89
+ const body = asRecord(raw);
90
+ if (body === null) {
91
+ return fail("image_edit_invalid", "Image edit body must be an object.");
92
+ }
93
+
94
+ if (isPresent(body.mask)) {
95
+ return fail(
96
+ "image_edit_mask_unsupported",
97
+ "Image edit masks are not supported.",
98
+ );
99
+ }
100
+
101
+ if (isPresent(body.style) || isPresent(body.background)) {
102
+ return fail(
103
+ "image_edit_invalid",
104
+ "Image edits do not support style or background options.",
105
+ );
106
+ }
107
+
108
+ const count = referenceCount(body);
109
+ if (count > 1) {
110
+ return fail(
111
+ "image_edit_multi_reference_unsupported",
112
+ "Image edits accept exactly one reference image.",
113
+ );
114
+ }
115
+
116
+ const url = referenceUrl(body);
117
+ if (url === null) {
118
+ return fail(
119
+ "image_edit_invalid",
120
+ "Image edits require exactly one reference image.",
121
+ );
122
+ }
123
+
124
+ const dataUrlBytes = estimateDataUrlBytes(url);
125
+ if (dataUrlBytes === null) {
126
+ return fail(
127
+ "image_edit_invalid",
128
+ "Image edit reference is not a valid base64 data URL.",
129
+ );
130
+ }
131
+ if (dataUrlBytes > IMAGE_EDIT_MAX_BODY_BYTES) {
132
+ return fail(
133
+ "image_edit_invalid",
134
+ `Image edit reference exceeds ${IMAGE_EDIT_MAX_BODY_BYTES} bytes.`,
135
+ );
136
+ }
137
+
138
+ const candidate: Record<string, unknown> = {
139
+ model: body.model,
140
+ prompt: body.prompt,
141
+ image: { url },
142
+ };
143
+ if (body.n !== undefined) candidate.n = body.n;
144
+ if (body.size !== undefined) candidate.size = body.size;
145
+ if (body.quality !== undefined) candidate.quality = body.quality;
146
+ if (body.response_format !== undefined) {
147
+ candidate.response_format = body.response_format;
148
+ }
149
+
150
+ const decoded = decodeImageEditRequest(candidate);
151
+ if (Result.isFailure(decoded)) {
152
+ return fail(
153
+ "image_edit_invalid",
154
+ "Image edit request is missing required fields or has invalid types.",
155
+ );
156
+ }
157
+ return { ok: true, request: decoded.success };
158
+ };
159
+
160
+ export type TImageEditMultipartFile = {
161
+ readonly fieldName: string;
162
+ readonly bytes: Uint8Array;
163
+ readonly contentType?: string;
164
+ };
165
+
166
+ // `String.fromCharCode(...bytes)` on the WHOLE array blows the call-stack /
167
+ // argument-count limit on a large image (spreads one argument per byte); a
168
+ // per-byte `+=` loop avoids that but is slow. Converting in bounded chunks
169
+ // gets the portable, allocation-cheap middle: each chunk is small enough for
170
+ // a safe spread, and the chunk strings are joined once at the end.
171
+ const BASE64_CHUNK_BYTES = 8192;
172
+
173
+ export const bytesToDataUrl = (
174
+ bytes: Uint8Array,
175
+ contentType: string | undefined,
176
+ ): string => {
177
+ const mime = contentType?.split(";")[0]?.trim() || "image/png";
178
+ const chunks: string[] = [];
179
+ for (let offset = 0; offset < bytes.length; offset += BASE64_CHUNK_BYTES) {
180
+ const chunk = bytes.subarray(offset, offset + BASE64_CHUNK_BYTES);
181
+ chunks.push(String.fromCharCode(...chunk));
182
+ }
183
+ return `data:${mime};base64,${btoa(chunks.join(""))}`;
184
+ };
185
+
186
+ // Multipart form fields arrive as bare strings; the shared schema
187
+ // (`ImageEditRequest.n: S.Number.pipe(S.int(), S.positive())`) requires a
188
+ // real number and does not coerce strings, so a multipart `n` must be
189
+ // normalized before it reaches `decodeImageEditRequest` — otherwise every
190
+ // multipart request that sets `n` (even a valid "1") fails with a generic
191
+ // schema error instead of the field actually being honored. Only a strict,
192
+ // bare positive-integer string is accepted: no `parseInt` (stops at the
193
+ // first non-digit, so "1abc" would silently become `1`) and no `Number()`
194
+ // coercion (`Number("")` and `Number(" ")` are both `0`, which would
195
+ // silently satisfy a blank/whitespace field). Anything else — empty,
196
+ // signed, fractional, hex, whitespace-padded, or non-numeric — is rejected
197
+ // explicitly here rather than passed through.
198
+ const POSITIVE_INTEGER_FIELD_PATTERN = /^[1-9][0-9]*$/;
199
+
200
+ const parseMultipartNField = (raw: string): number | null =>
201
+ POSITIVE_INTEGER_FIELD_PATTERN.test(raw) ? Number(raw) : null;
202
+
203
+ /**
204
+ * Map OpenAI-style multipart edits (`image` file + string fields) onto the
205
+ * same canonical parser as JSON.
206
+ */
207
+ export const parseImageEditMultipart = (input: {
208
+ readonly fields: Readonly<Record<string, string>>;
209
+ readonly files: ReadonlyArray<TImageEditMultipartFile>;
210
+ }): TImageEditParseResult => {
211
+ const imageFiles = input.files.filter(
212
+ (file) => file.fieldName === "image" || file.fieldName === "images",
213
+ );
214
+ const maskFiles = input.files.filter((file) => file.fieldName === "mask");
215
+ if (maskFiles.length > 0 || isPresent(input.fields.mask)) {
216
+ return fail(
217
+ "image_edit_mask_unsupported",
218
+ "Image edit masks are not supported.",
219
+ );
220
+ }
221
+ if (imageFiles.length > 1) {
222
+ return fail(
223
+ "image_edit_multi_reference_unsupported",
224
+ "Image edits accept exactly one reference image.",
225
+ );
226
+ }
227
+ // A file field AND an inline `image`/`images` string field together are an
228
+ // ambiguous duplicate reference (which one wins?) — reject explicitly
229
+ // rather than silently letting the file overwrite the string field below.
230
+ if (
231
+ imageFiles.length === 1 &&
232
+ (isPresent(input.fields.image) || isPresent(input.fields.images))
233
+ ) {
234
+ return fail(
235
+ "image_edit_multi_reference_unsupported",
236
+ "Image edits accept exactly one reference image; do not combine an image file with an inline image field.",
237
+ );
238
+ }
239
+
240
+ const raw: Record<string, unknown> = { ...input.fields };
241
+ if (imageFiles.length === 1) {
242
+ const file = imageFiles[0];
243
+ if (file !== undefined) {
244
+ raw.image = bytesToDataUrl(file.bytes, file.contentType);
245
+ }
246
+ }
247
+ if (typeof input.fields.n === "string") {
248
+ const n = parseMultipartNField(input.fields.n);
249
+ if (n === null) {
250
+ return fail(
251
+ "image_edit_invalid",
252
+ 'Image edit "n" must be a positive integer.',
253
+ );
254
+ }
255
+ raw.n = n;
256
+ }
257
+ return parseImageEditInput(raw);
258
+ };
259
+
260
+ export const isImageEditRequest = (
261
+ value: TImageEditParseResult,
262
+ ): value is { readonly ok: true; readonly request: TImageEditRequest } =>
263
+ value.ok;