@descix/platform-api 1.0.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.
package/src/index.js ADDED
@@ -0,0 +1,107 @@
1
+ /**
2
+ * @descix/platform-api
3
+ *
4
+ * Shared platform infrastructure for DeSciX microservices.
5
+ * Sits between @descix/cloud-core (GCP infra) and consuming services (Cloud + Powch).
6
+ *
7
+ * Sub-module exports are also available via named paths:
8
+ * import { ... } from '@descix/platform-api/models'
9
+ * import { ... } from '@descix/platform-api/auth'
10
+ * import { ... } from '@descix/platform-api/email'
11
+ * import { ... } from '@descix/platform-api/permissions'
12
+ * import { ... } from '@descix/platform-api/entitlements'
13
+ * import { ... } from '@descix/platform-api/manifest'
14
+ */
15
+
16
+ // Models
17
+ export {
18
+ Role,
19
+ App,
20
+ User,
21
+ Community,
22
+ UserCommunityStats,
23
+ GuildSettings,
24
+ Promotion,
25
+ NFT,
26
+ AdCampaign,
27
+ SharedAsset,
28
+ clean_name_for_id,
29
+ count_tokens,
30
+ matrix_to_bigquery,
31
+ sanitizeCredentialId,
32
+ get_default_community,
33
+ getUserEntitlements
34
+ } from './models/index.js';
35
+
36
+ // Auth
37
+ export {
38
+ createUserSession,
39
+ sendEmailVerification,
40
+ verifyEmailCode,
41
+ migrateUserIfNeeded
42
+ } from './auth/index.js';
43
+
44
+ // Email
45
+ export {
46
+ sendEmail,
47
+ sendVerificationEmail,
48
+ sendPaymentPending,
49
+ sendPaymentConfirmation,
50
+ normalizeEmail,
51
+ base64UrlEncode
52
+ } from './email/index.js';
53
+
54
+ // Permissions
55
+ export {
56
+ checkRoleBasedPermission,
57
+ hasAnyAdminAccess,
58
+ getUserAdminScope
59
+ } from './permissions/index.js';
60
+
61
+ // Entitlements
62
+ export {
63
+ hydrateCommunityIdFromProducts
64
+ } from './entitlements/index.js';
65
+
66
+ // Manifest (service discovery)
67
+ export {
68
+ buildManifestFromHandlers,
69
+ buildManifestFromStatic,
70
+ validateManifest,
71
+ manifestMiddleware,
72
+ computeManifestHash,
73
+ computeManifestObjectHash
74
+ } from './manifest/index.js';
75
+
76
+ // Coordination-fabric vocabulary (a pure, dependency-free leaf; also at
77
+ // @descix/platform-api/fabric). Re-exported here so a consumer that already imports the package
78
+ // root does not reach for `src/fabric/vocab.js` by path and pin itself to a file location.
79
+ export {
80
+ BEAT_CLOCK_FIELDS,
81
+ BEAT_CLOCK_FIELD_NAMES,
82
+ beatClockFieldFor,
83
+ normalizeBeatClocks,
84
+ judgeModelLiveness,
85
+ beatClockAgeSeconds,
86
+ beatClockAgeField,
87
+ BEAT_CLOCK_AGE_FIELDS,
88
+ } from './fabric/index.js';
89
+
90
+ // Canonical id derivation (token <-> community <-> app)
91
+ export {
92
+ communityIdFromTokenSymbol,
93
+ assertValidAppShortName,
94
+ composeAppId,
95
+ composeUserAppId,
96
+ composeUserDocServeUrl,
97
+ TOKEN_SYMBOL_RE,
98
+ APP_SHORT_NAME_RE,
99
+ // Service domain — the platform derives it; a service never declares one.
100
+ SERVICE_DOMAIN_IS_DERIVED,
101
+ composeServiceDomain,
102
+ isAppBoundService,
103
+ resolveServiceDomain,
104
+ // Reading a STORED manifest: the routable origin, or a loud refusal.
105
+ SERVICE_NOT_ROUTABLE,
106
+ requireServiceOrigin
107
+ } from './naming/index.js';
@@ -0,0 +1,13 @@
1
+ /**
2
+ * MOVED. The owner of this surface is now `@descix/cloud-core/manifest`.
3
+ *
4
+ * This file is a RE-EXPORT, not a copy, and that distinction is the point: during the move
5
+ * there must never be an instant at which two locations hold the same fact. A copy left here
6
+ * would be a second owner for as long as the companion repoint takes; a pointer is the same
7
+ * owner reached by an older name.
8
+ *
9
+ * It exists only until DeSciX_Cloud's imports are repointed at `@descix/cloud-core/manifest`,
10
+ * after which this file and its subpath export are DELETED. That repoint is a companion row
11
+ * and is deliberately NOT part of this change.
12
+ */
13
+ export * from '@descix/cloud-core/manifest';
@@ -0,0 +1,387 @@
1
+ /**
2
+ * chatMedia — THE canonical contract for MEDIA entering a chat turn.
3
+ *
4
+ * ONE OWNER RULE (ws-chat-multimodal-image-attach, extending WS-B8's chatIngress):
5
+ * text contributions enter a turn through `chatIngress` (descix-app-sdk); MEDIA
6
+ * contributions carry bytes, and bytes need a wire shape, a MIME vocabulary, a size
7
+ * policy and a provider-block encoder. All four live HERE, once. No consumer
8
+ * re-enumerates a MIME list, re-derives a byte cap, or hand-writes a provider block.
9
+ *
10
+ * ## Why this module is in @descix/platform-api and not in chatIngress
11
+ *
12
+ * chatIngress lives in `@descix/app-sdk`, which is a BROWSER package (React/MUI/viem) and
13
+ * does NOT depend on platform-api; platform-api depends on `googleapis` and is server-side.
14
+ * Making the browser package import this one would drag googleapis into a browser bundle,
15
+ * and duplicating the constants into both would be exactly the schema-mirror drift the
16
+ * engineering-culture mandate forbids. So the SERVER is the single validation authority:
17
+ * chatIngress owns the client-side contribution SHAPE (a media attachment is a staged
18
+ * contribution, not a second ingress), and this module owns the WIRE and the POLICY. A
19
+ * client that sends something inadmissible is refused loudly by the server, naming the
20
+ * limit it broke — it is never silently trimmed.
21
+ *
22
+ * ## Probe-verified provider facts (@google/genai 2.16.0 Interactions API, live 2026-08-20)
23
+ * These are MEASURED, not inferred from generateContent docs — do not re-derive:
24
+ * - `interactions.create({ input })` accepts `string | Step[] | Content[] | Turn[] | Content`.
25
+ * Turn[] (role-bearing) is REJECTED on this API version with "When using the steps-based
26
+ * API version, use step_list input format instead of turn_list", and `{role, parts}` is
27
+ * rejected with "Unknown parameter 'parts'". The admissible multimodal form is a FLAT
28
+ * array of typed content blocks:
29
+ * [ { type:'text', text }, { type:'image', mime_type, data } ]
30
+ * - block `type` vocabulary: text | document | image | audio | video | thought | *_call | *_result.
31
+ * - media blocks are FLAT and snake_case: `{ type, mime_type, data }`. There is NO
32
+ * `inlineData` / `fileData` / `source` wrapper here — those belong to the classic
33
+ * generateContent Part and are rejected ("Unknown parameter 'inlineData'"). The SDK does
34
+ * NO key-casing transformation on this surface: what you type is what goes on the wire.
35
+ * - `{ type:'image', uri:'gs://…' }` is REJECTED: "Referencing Google Cloud Storage files
36
+ * directly is not supported. Register them using FileService.RegisterFile first."
37
+ * THIS IS WHY app-space GCS references are resolved to BYTES server-side (the platform
38
+ * reads its own private bucket through its own canonical asset reader) rather than handed
39
+ * to the provider as a URI. A gs:// path is a DeSciX-side reference, never a provider one.
40
+ * - the provider returns a per-modality token breakdown on `usage.input_tokens_by_modality`,
41
+ * so media tokens are counted by the provider and already land in `total_input_tokens` /
42
+ * `total_tokens`. Measured: text-only turn 21 input tokens; same turn + one 640x360 PNG
43
+ * 1096 (image 1075 + text 21); a 3s 320x240 MP4 189 video tokens.
44
+ */
45
+
46
+ /**
47
+ * The media kinds this platform accepts TODAY.
48
+ *
49
+ * The provider also accepts 'audio' and 'document' blocks with a structurally identical
50
+ * shape, and adding them here is a two-line change — but they are deliberately NOT enabled,
51
+ * because they have not been live-measured on this surface and the platform does not ship
52
+ * capabilities it has not observed working (working-discipline mandate). An audio/document
53
+ * attachment is refused by name, pointing at this comment, rather than silently accepted
54
+ * into an unverified path.
55
+ */
56
+ export const CHAT_MEDIA_KINDS = Object.freeze(['image', 'video']);
57
+
58
+ /**
59
+ * MIME allow-list per kind, taken from the SDK's own typed unions
60
+ * (`ImageContentMimeType` / `VideoContentMimeType`, genai.d.ts). An unlisted MIME FAILS
61
+ * LOUD rather than being forwarded on the hope the provider tolerates it: a rejected
62
+ * upstream call costs a metered round-trip and produces a far worse error message.
63
+ */
64
+ export const CHAT_MEDIA_MIME_TYPES = Object.freeze({
65
+ image: Object.freeze([
66
+ 'image/png', 'image/jpeg', 'image/webp', 'image/heic',
67
+ 'image/heif', 'image/gif', 'image/bmp', 'image/tiff',
68
+ ]),
69
+ video: Object.freeze([
70
+ 'video/mp4', 'video/mpeg', 'video/mpg', 'video/mov', 'video/avi',
71
+ 'video/x-flv', 'video/webm', 'video/wmv', 'video/3gpp',
72
+ ]),
73
+ });
74
+
75
+ /**
76
+ * SIZE POLICY — set against the MEASURED producer numbers, not guesses
77
+ * (godsworld/design/frqtl-producer-contract.md, "MEASURED size arithmetic"):
78
+ *
79
+ * a 24-frame 600x600 flyby as base64 MP4 ~ 373 KB <- the COMMON CASE
80
+ * the same flyby as a base64 PNG sequence ~ 1.78 MB
81
+ * a single 600x600 still as base64 PNG ~ 78 KB
82
+ *
83
+ * 8 MiB per attachment is ~22x the common-case flyby, so a longer flight or a higher
84
+ * resolution still fits, while a runaway producer cannot put an unbounded blob on a
85
+ * metered turn. 16 MiB per turn bounds the whole turn even with several attachments.
86
+ *
87
+ * Caps are DECODED byte counts (what the provider bills against), not base64 lengths —
88
+ * base64 inflates by 4/3 and a policy expressed in encoded length would silently be 25%
89
+ * tighter than it reads.
90
+ *
91
+ * UNLIKE TEXT, OVERSIZE MEDIA IS REJECTED, NOT TRUNCATED. chatIngress truncates an
92
+ * oversized text result because a prefix of text is still meaningful. A prefix of an MP4
93
+ * is a CORRUPT FILE: the model would receive something undecodable, or worse, decodable
94
+ * but wrong. So the size policy here fails loud with the numbers named.
95
+ */
96
+ export const MAX_MEDIA_BYTES = 8 * 1024 * 1024;
97
+ export const MAX_TURN_MEDIA_BYTES = 16 * 1024 * 1024;
98
+ export const MAX_MEDIA_ATTACHMENTS_PER_TURN = 8;
99
+
100
+ /** Decoded byte length of a base64 payload, without allocating the buffer to find out. */
101
+ export function base64DecodedBytes(b64) {
102
+ if (typeof b64 !== 'string' || b64.length === 0) return 0;
103
+ const clean = b64.endsWith('==') ? b64.slice(0, -2) : b64.endsWith('=') ? b64.slice(0, -1) : b64;
104
+ return Math.floor((clean.length * 3) / 4);
105
+ }
106
+
107
+ /** Human-readable byte size for error messages that have to be actionable. */
108
+ function humanBytes(n) {
109
+ if (n >= 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(2)} MiB`;
110
+ if (n >= 1024) return `${(n / 1024).toFixed(1)} KiB`;
111
+ return `${n} B`;
112
+ }
113
+
114
+ /**
115
+ * Which kind does this MIME belong to? Returns null for anything unlisted — callers decide
116
+ * whether that is a fail-loud (it always is, today).
117
+ */
118
+ export function kindForMimeType(mime) {
119
+ if (typeof mime !== 'string') return null;
120
+ const m = mime.toLowerCase().trim();
121
+ for (const kind of CHAT_MEDIA_KINDS) {
122
+ if (CHAT_MEDIA_MIME_TYPES[kind].includes(m)) return kind;
123
+ }
124
+ return null;
125
+ }
126
+
127
+ /** Every MIME the platform accepts, flat — used to build schema descriptions (DRY). */
128
+ export function allAcceptedMimeTypes() {
129
+ return CHAT_MEDIA_KINDS.flatMap((k) => CHAT_MEDIA_MIME_TYPES[k]);
130
+ }
131
+
132
+ /**
133
+ * A media attachment arrives one of exactly TWO ways, and never both:
134
+ * - 'inline' : `data` is base64 bytes the caller already holds.
135
+ * - 'asset_ref' : `asset_ref` names an object in THIS APP's own GCS assets space
136
+ * (a `gs://` URI or a path relative to the app's assets/ prefix), which
137
+ * the server resolves to bytes through the canonical app-asset reader.
138
+ * Declaring both is a caller bug (which one did you mean?) and is refused.
139
+ */
140
+ export const MEDIA_SOURCES = Object.freeze(['inline', 'asset_ref']);
141
+
142
+ /**
143
+ * normalize(partial) -> full bag. THE contract. Consumers ferry this bag; they never
144
+ * hand-list its fields (schema-mirror drift is a bug class — engineering-culture mandate).
145
+ *
146
+ * FAIL LOUD on anything malformed. A silently-dropped attachment is the worst outcome
147
+ * available here: the model answers confidently about an image it never received, and
148
+ * nothing in the transcript says so.
149
+ *
150
+ * @param {Object} partial - { mime_type, data? , asset_ref?, label?, truncated?, track? }
151
+ * @returns {Object} the full normalized bag
152
+ */
153
+ export function normalizeMediaAttachment(partial) {
154
+ if (!partial || typeof partial !== 'object' || Array.isArray(partial)) {
155
+ throw new TypeError('[chatMedia] media attachment must be an object');
156
+ }
157
+ const { mime_type, data, asset_ref, label, track } = partial;
158
+
159
+ if (typeof mime_type !== 'string' || !mime_type.trim()) {
160
+ throw new TypeError(
161
+ `[chatMedia] media attachment is missing mime_type. Accepted: ${allAcceptedMimeTypes().join(', ')}`
162
+ );
163
+ }
164
+ const kind = kindForMimeType(mime_type);
165
+ if (!kind) {
166
+ // Name the two the provider supports but this platform has not measured, so the caller
167
+ // understands the refusal is a scope boundary and not a typo on their side.
168
+ const unverified = /^audio\//i.test(mime_type) || /^application\/pdf$/i.test(mime_type);
169
+ throw new TypeError(
170
+ `[chatMedia] unsupported media mime_type "${mime_type}"` +
171
+ (unverified
172
+ ? ' — audio and document attachments are not enabled on this surface yet (not live-verified).'
173
+ : '') +
174
+ ` Accepted: ${allAcceptedMimeTypes().join(', ')}`
175
+ );
176
+ }
177
+
178
+ const hasInline = typeof data === 'string' && data.length > 0;
179
+ const hasRef = typeof asset_ref === 'string' && asset_ref.length > 0;
180
+ if (hasInline && hasRef) {
181
+ throw new TypeError(
182
+ '[chatMedia] media attachment declares BOTH data and asset_ref — supply exactly one ' +
183
+ '(inline bytes, or a reference into the app\'s asset space).'
184
+ );
185
+ }
186
+ if (!hasInline && !hasRef) {
187
+ throw new TypeError(
188
+ '[chatMedia] media attachment has neither data (base64 bytes) nor asset_ref ' +
189
+ '(a gs:// URI or a path under the app\'s assets/ prefix).'
190
+ );
191
+ }
192
+
193
+ // Size policy applies to inline bytes at the door. An asset_ref is sized AFTER the server
194
+ // resolves it (assertMediaBytesWithinPolicy), because only then are the bytes known.
195
+ let bytes = null;
196
+ if (hasInline) {
197
+ if (/\s/.test(data.slice(0, 64)) && data.trimStart().startsWith('data:')) {
198
+ throw new TypeError(
199
+ '[chatMedia] media `data` must be RAW base64, not a data: URL. ' +
200
+ 'Strip the "data:<mime>;base64," prefix and pass mime_type separately.'
201
+ );
202
+ }
203
+ bytes = base64DecodedBytes(data);
204
+ assertMediaBytesWithinPolicy(bytes, { label: label || kind, mime_type });
205
+ }
206
+
207
+ return {
208
+ kind,
209
+ mime_type: mime_type.toLowerCase().trim(),
210
+ source: hasInline ? 'inline' : 'asset_ref',
211
+ data: hasInline ? data : null,
212
+ asset_ref: hasRef ? asset_ref : null,
213
+ label: label || kind,
214
+ bytes,
215
+ // Ferried straight from the producer's sidecar manifest, NOT re-derived here.
216
+ // `truncated` means the PRODUCER shortened the capture (FlightRecorder.overflowed).
217
+ // It is made MODEL-VISIBLE by mediaTruncationNotice below — losing the flag in
218
+ // transport would re-introduce, one layer up, exactly the observability lie the
219
+ // recorder treats as a bug class (frqtl-producer-contract.md).
220
+ truncated: partial.truncated === true,
221
+ // Opaque provenance bag (scene hash, tick indices, frame table, fps/ticksPerFrame…).
222
+ // Ferried verbatim so the VLA loop can align a prediction with the state that produced
223
+ // it. We deliberately do NOT re-enumerate its fields: the producer owns that schema.
224
+ track: track && typeof track === 'object' ? track : null,
225
+ };
226
+ }
227
+
228
+ /**
229
+ * Enforce the per-attachment cap. Separate from normalize() because an asset_ref's size is
230
+ * only knowable after the server has resolved the object.
231
+ */
232
+ export function assertMediaBytesWithinPolicy(bytes, { label = 'attachment', mime_type = '' } = {}) {
233
+ if (bytes > MAX_MEDIA_BYTES) {
234
+ const err = new Error(
235
+ `[chatMedia] media attachment "${label}" (${mime_type}) is ${humanBytes(bytes)}, over the ` +
236
+ `${humanBytes(MAX_MEDIA_BYTES)} per-attachment limit. Media is REJECTED rather than truncated — ` +
237
+ `a partial video or image is a corrupt file, not a shorter one. Re-encode smaller ` +
238
+ `(for a flyby, an MP4 is ~5x smaller than the equivalent PNG sequence) and retry.`
239
+ );
240
+ err.code = 'MEDIA_TOO_LARGE';
241
+ err.data = { label, mime_type, bytes, limit: MAX_MEDIA_BYTES };
242
+ throw err;
243
+ }
244
+ return bytes;
245
+ }
246
+
247
+ /**
248
+ * Normalize a whole turn's worth of attachments and enforce the per-TURN bounds.
249
+ * @param {Array} list
250
+ * @returns {Array} normalized bags
251
+ */
252
+ export function normalizeMediaAttachments(list) {
253
+ if (list === undefined || list === null) return [];
254
+ if (!Array.isArray(list)) {
255
+ throw new TypeError('[chatMedia] `media` must be an array of media attachments');
256
+ }
257
+ if (list.length > MAX_MEDIA_ATTACHMENTS_PER_TURN) {
258
+ const err = new Error(
259
+ `[chatMedia] ${list.length} media attachments on one turn, over the ` +
260
+ `${MAX_MEDIA_ATTACHMENTS_PER_TURN} per-turn limit.`
261
+ );
262
+ err.code = 'MEDIA_TOO_MANY';
263
+ err.data = { count: list.length, limit: MAX_MEDIA_ATTACHMENTS_PER_TURN };
264
+ throw err;
265
+ }
266
+ const bags = list.map(normalizeMediaAttachment);
267
+ assertTurnMediaWithinPolicy(bags);
268
+ return bags;
269
+ }
270
+
271
+ /** Enforce the per-turn aggregate byte cap over whatever sizes are known so far. */
272
+ export function assertTurnMediaWithinPolicy(bags) {
273
+ const total = bags.reduce((sum, b) => sum + (b.bytes || 0), 0);
274
+ if (total > MAX_TURN_MEDIA_BYTES) {
275
+ const err = new Error(
276
+ `[chatMedia] this turn carries ${humanBytes(total)} of media, over the ` +
277
+ `${humanBytes(MAX_TURN_MEDIA_BYTES)} per-turn limit. Send fewer or smaller attachments.`
278
+ );
279
+ err.code = 'MEDIA_TURN_TOO_LARGE';
280
+ err.data = { bytes: total, limit: MAX_TURN_MEDIA_BYTES };
281
+ throw err;
282
+ }
283
+ return total;
284
+ }
285
+
286
+ /**
287
+ * The MODEL-VISIBLE notice for producer-truncated media, mirroring chatIngress's
288
+ * truncationMarker contract: the model must know it is reasoning over a prefix.
289
+ * Returns '' when nothing was truncated, so callers can concatenate unconditionally.
290
+ */
291
+ export function mediaTruncationNotice(bags) {
292
+ const cut = bags.filter((b) => b.truncated);
293
+ if (cut.length === 0) return '';
294
+ const names = cut.map((b) => `"${b.label}"`).join(', ');
295
+ return (
296
+ `\n\n… [TRUNCATED at capture by the producer: ${names} ${cut.length === 1 ? 'is' : 'are'} a PREFIX of the ` +
297
+ `recording, not the whole of it. Frames after the cut were never captured — do not infer that ` +
298
+ `nothing happened after the last frame you can see.]`
299
+ );
300
+ }
301
+
302
+ /**
303
+ * Encode one normalized bag as the provider's typed content block.
304
+ * THE ONLY PLACE that knows the wire shape. Probe-verified flat snake_case:
305
+ * { type:'image'|'video', mime_type:'image/png', data:'<base64>' }
306
+ *
307
+ * An unresolved asset_ref reaching here is a programming error in the server pipeline
308
+ * (the resolver runs first), not a caller error — it fails loud as such.
309
+ */
310
+ export function toProviderBlock(bag) {
311
+ if (!bag || !CHAT_MEDIA_KINDS.includes(bag.kind)) {
312
+ throw new TypeError(`[chatMedia] cannot encode media block for kind "${bag && bag.kind}"`);
313
+ }
314
+ if (typeof bag.data !== 'string' || !bag.data.length) {
315
+ throw new Error(
316
+ `[chatMedia] media "${bag.label}" has no bytes at encode time` +
317
+ (bag.asset_ref ? ` — its asset_ref "${bag.asset_ref}" was never resolved.` : '.')
318
+ );
319
+ }
320
+ return { type: bag.kind, mime_type: bag.mime_type, data: bag.data };
321
+ }
322
+
323
+ /**
324
+ * Build the whole provider `input` for a turn: the text block first, then one block per
325
+ * attachment. Text-first so the model reads the instruction before the pixels, matching
326
+ * chatIngress.composeTurnInput's ordering rationale.
327
+ *
328
+ * Returns a STRING when there is no media, so the existing text-only path is byte-for-byte
329
+ * unchanged (the API accepts a bare string, and every prior probe/measurement was taken
330
+ * against that form).
331
+ */
332
+ export function buildProviderInput(text, bags = []) {
333
+ if (!bags || bags.length === 0) return text;
334
+ return [{ type: 'text', text: text + mediaTruncationNotice(bags) }, ...bags.map(toProviderBlock)];
335
+ }
336
+
337
+ /**
338
+ * The JSON-Schema fragment for the `media` parameter, so nativeTools.js DECLARES the
339
+ * contract instead of restating it. One owner for the vocabulary and the caps means the
340
+ * advertised schema can never drift from the enforced policy.
341
+ */
342
+ export function mediaParamSchema() {
343
+ return {
344
+ type: 'array',
345
+ description:
346
+ 'Optional: images and/or videos for the model to LOOK AT on this turn. Each entry supplies ' +
347
+ 'EITHER `data` (raw base64 bytes, no data: URL prefix) OR `asset_ref` (a gs:// URI or a path ' +
348
+ 'relative to this app\'s assets/ prefix, uploaded via `descix app media-upload` / ' +
349
+ 'get_asset_upload_token) — exactly one, never both. Media persists in the conversation thread: ' +
350
+ 'on a later turn with previous_interaction_id the model still remembers it, so do NOT resend. ' +
351
+ `Limits: up to ${MAX_MEDIA_ATTACHMENTS_PER_TURN} attachments/turn, ` +
352
+ `${Math.round(MAX_MEDIA_BYTES / (1024 * 1024))} MiB each, ` +
353
+ `${Math.round(MAX_TURN_MEDIA_BYTES / (1024 * 1024))} MiB per turn. Oversized media is REJECTED, ` +
354
+ 'not truncated. Media tokens are billed as input tokens.',
355
+ items: {
356
+ type: 'object',
357
+ properties: {
358
+ mime_type: {
359
+ type: 'string',
360
+ enum: allAcceptedMimeTypes(),
361
+ description: 'MIME type of the attachment; determines whether it is sent as an image or a video block.',
362
+ },
363
+ data: { type: 'string', description: 'Raw base64-encoded bytes. Mutually exclusive with asset_ref.' },
364
+ asset_ref: {
365
+ type: 'string',
366
+ description:
367
+ 'Reference to an object in THIS app\'s GCS asset space (gs:// URI, or a path relative to the ' +
368
+ 'app assets/ prefix). Resolved to bytes server-side. Mutually exclusive with data.',
369
+ },
370
+ label: { type: 'string', description: 'Short human/model-readable name for this attachment.' },
371
+ truncated: {
372
+ type: 'boolean',
373
+ description:
374
+ 'Set true when the PRODUCER shortened the capture (e.g. FlightRecorder overflow). The model is ' +
375
+ 'told explicitly that it is seeing a prefix.',
376
+ },
377
+ track: {
378
+ type: 'object',
379
+ description:
380
+ 'Optional provenance sidecar ferried verbatim (scene hash, tick indices, frame table, ' +
381
+ 'ticksPerFrame/fps). Lets a VLA loop align a prediction with the state that produced it.',
382
+ },
383
+ },
384
+ required: ['mime_type'],
385
+ },
386
+ };
387
+ }