@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/LICENSE.md +671 -0
- package/README.md +53 -0
- package/package.json +39 -0
- package/src/auth/emailVerification.js +108 -0
- package/src/auth/index.js +9 -0
- package/src/auth/migration.js +96 -0
- package/src/auth/session.js +33 -0
- package/src/email/index.js +259 -0
- package/src/entitlements/index.js +86 -0
- package/src/fabric/index.js +8 -0
- package/src/fabric/vocab.js +1402 -0
- package/src/index.js +107 -0
- package/src/manifest/index.js +13 -0
- package/src/mcp-tools/chatMedia.js +387 -0
- package/src/mcp-tools/evidence-contract.js +324 -0
- package/src/mcp-tools/handshake.js +69 -0
- package/src/mcp-tools/index.js +107 -0
- package/src/mcp-tools/nativeTools.js +902 -0
- package/src/mcp-tools/paramValidation.js +562 -0
- package/src/mcp-tools/recordFilter.js +88 -0
- package/src/mcp-tools/setup-playbook.js +277 -0
- package/src/models/index.js +1901 -0
- package/src/naming/index.js +13 -0
- package/src/permissions/index.js +157 -0
- package/src/service-bootstrap/index.js +13 -0
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
|
+
}
|