@lobu/runtime-device 20.0.1 → 20.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/dist/component.json +1 -1
  2. package/dist/dependencies.bun.lock +8 -8
  3. package/npm-shrinkwrap.json +32 -32
  4. package/package.json +1 -1
  5. package/vendor/cli/dist/commands/_lib/apply/map-config.js +7 -3
  6. package/vendor/cli/dist/commands/call.d.ts +2 -1
  7. package/vendor/cli/dist/commands/call.js +8 -2
  8. package/vendor/cli/dist/commands/dev.js +2 -2
  9. package/vendor/cli/dist/commands/doctor.js +3 -12
  10. package/vendor/cli/dist/commands/init.js +15 -3
  11. package/vendor/cli/dist/commands/memory/_lib/errors.d.ts +12 -0
  12. package/vendor/cli/dist/commands/memory/_lib/errors.js +21 -0
  13. package/vendor/cli/dist/commands/memory/run.js +7 -1
  14. package/vendor/cli/dist/commands/telemetry.js +2 -11
  15. package/vendor/cli/dist/commands/token.js +20 -3
  16. package/vendor/cli/dist/connectors/chat-user-identity.ts +45 -0
  17. package/vendor/cli/dist/connectors/google-identity.ts +107 -0
  18. package/vendor/cli/dist/connectors/google_drive.ts +36 -151
  19. package/vendor/cli/dist/connectors/google_gmail.ts +149 -0
  20. package/vendor/cli/dist/connectors/microsoft_outlook.ts +193 -0
  21. package/vendor/cli/dist/connectors/slack-identity.ts +20 -0
  22. package/vendor/cli/dist/internal/credentials.js +8 -0
  23. package/vendor/cli/dist/internal/env-file.d.ts +8 -0
  24. package/vendor/cli/dist/internal/env-file.js +21 -0
  25. package/vendor/cli/dist/runtime-components.json +4 -4
  26. package/vendor/cli/package.json +1 -1
  27. package/vendor/connector-sdk/dist/file-output.d.ts +97 -0
  28. package/vendor/connector-sdk/dist/file-output.js +176 -0
  29. package/vendor/connector-sdk/dist/index.d.ts +2 -0
  30. package/vendor/connector-sdk/dist/index.js +1 -0
  31. package/vendor/connector-sdk/package.json +1 -1
  32. package/vendor/connector-worker/dist/executor/isolate.js +6 -1
  33. package/vendor/connector-worker/package.json +1 -1
  34. package/vendor/core/dist/classify-error.js +50 -2
  35. package/vendor/core/dist/constants.d.ts +13 -6
  36. package/vendor/core/dist/constants.js +22 -8
  37. package/vendor/core/dist/errors.d.ts +20 -0
  38. package/vendor/core/dist/errors.js +21 -1
  39. package/vendor/core/package.json +1 -1
@@ -0,0 +1,107 @@
1
+ /**
2
+ * Google connector identity namespace and normalization.
3
+ *
4
+ * Single source of truth for `google_user_id` rules. Google sign-in writes it;
5
+ * the Google Chat sender lookup reads it. Connector-specific identity knowledge
6
+ * stays in the connector package so core code never names Google.
7
+ *
8
+ * WHY ONE NAMESPACE SERVES BOTH: a Google Chat `User.name` is `users/{id}`,
9
+ * where `{id}` is the same account id Google puts in the OIDC `sub` claim. So
10
+ * the Chat sender and the web signer are keyed identically, with no directory
11
+ * lookup in between. This was confirmed against real accounts before relying on
12
+ * it — the Chat-side user cache and the stored OIDC `sub` agree digit for
13
+ * digit — not inferred from Google's documentation alone.
14
+ */
15
+
16
+ import type { ChatUserIdentity } from './chat-user-identity.js';
17
+ import type { ConnectorIdentityModule } from './connector-identity-module.js';
18
+
19
+ /** Connector-owned identity namespaces (not SDK-global). */
20
+ export const GOOGLE_IDENTITY = {
21
+ /**
22
+ * The Google account id (the OIDC `sub`), bare and unscoped. Unlike Slack's
23
+ * `T…:U…`, this needs no tenant prefix: Google account ids are unique across
24
+ * all of Google, so there is no second workspace that can mint the same id.
25
+ */
26
+ USER_ID: 'google_user_id',
27
+ } as const;
28
+
29
+ export type GoogleIdentityNamespace =
30
+ (typeof GOOGLE_IDENTITY)[keyof typeof GOOGLE_IDENTITY];
31
+
32
+ /** Google Chat addresses a person as `users/{id}`; the stored key is bare. */
33
+ const GCHAT_USER_PREFIX = 'users/';
34
+
35
+ /**
36
+ * Canonicalize a Google account id to its bare numeric form, accepting either
37
+ * the raw ~21-digit id as the OIDC `sub` delivers it, or the Google Chat
38
+ * resource name that wraps the same digits as `users/<id>`.
39
+ *
40
+ * Digits only, deliberately, and that rule is load-bearing rather than mere
41
+ * hygiene. Not every stored Google OAuth account is a sign-in: a Google
42
+ * CONNECTOR grant (drive/gmail/calendar) writes one too, under a synthetic
43
+ * account id such as `connect_<n>_<n>` or `lobu-connector:<org>:google.drive:<id>`.
44
+ * A connector authorization is a different consent from proving who you are, so
45
+ * it must not mint a chat identity — and some of those grants DO request
46
+ * `openid`, so a scope check would not separate them. The numeric rule does.
47
+ *
48
+ * It also refuses a Chat app id, a service-account resource name, an id from
49
+ * another platform, and an empty string. Returns null when the value is not a
50
+ * bare Google account id.
51
+ */
52
+ export function normalizeGoogleUserId(
53
+ raw: string | null | undefined,
54
+ ): string | null {
55
+ if (typeof raw !== 'string') return null;
56
+ const trimmed = raw.trim();
57
+ if (!trimmed) return null;
58
+ const bare = trimmed.startsWith(GCHAT_USER_PREFIX)
59
+ ? trimmed.slice(GCHAT_USER_PREFIX.length)
60
+ : trimmed;
61
+ // Bounded length: a Google account id is ~21 digits. The cap keeps an
62
+ // unbounded string out of an indexed identity column.
63
+ return /^[0-9]{1,32}$/.test(bare) ? bare : null;
64
+ }
65
+
66
+ /**
67
+ * Normalize a Google identity namespace value. Returns `undefined` when the
68
+ * namespace is not Google-owned (caller should fall back to generic hygiene).
69
+ */
70
+ export function normalizeGoogleIdentityValue(
71
+ namespace: string,
72
+ raw: string,
73
+ ): string | null | undefined {
74
+ switch (namespace) {
75
+ case GOOGLE_IDENTITY.USER_ID:
76
+ return normalizeGoogleUserId(raw);
77
+ default:
78
+ return undefined;
79
+ }
80
+ }
81
+
82
+ /** The Google connector's contribution to the server identity wiring. */
83
+ export const googleIdentityModule: ConnectorIdentityModule = {
84
+ key: 'google',
85
+ // Not recall-indexed: `google_user_id` links a signer to a chat sender, it is
86
+ // not an event-recall key, so it ships no `idx_events_metadata_*` index.
87
+ recallNamespaces: [],
88
+ normalize: normalizeGoogleIdentityValue,
89
+ };
90
+
91
+ /**
92
+ * Google Chat's sender-identity model: a `gchat` message's sender is keyed by
93
+ * the bare Google account id, which a `google` sign-in proves.
94
+ *
95
+ * `teamId` is ignored on purpose. Slack needs it because two workspaces can
96
+ * both contain `U12345`; Google cannot produce two accounts with one id, so
97
+ * there is nothing to scope by and no cross-tenant bleed to prevent. Inbound
98
+ * Google Chat events carry no workspace id anyway.
99
+ */
100
+ export const gchatChatUserIdentity: ChatUserIdentity = {
101
+ platform: 'gchat',
102
+ providerId: 'google',
103
+ namespace: GOOGLE_IDENTITY.USER_ID,
104
+ buildUserKey(_teamId, platformUserId) {
105
+ return normalizeGoogleUserId(platformUserId);
106
+ },
107
+ };
@@ -21,6 +21,12 @@
21
21
  */
22
22
 
23
23
  import {
24
+ downloadSizeError,
25
+ fileDownloadOutput,
26
+ inlineContentBudget,
27
+ inlineMaxBytesSchema,
28
+ inlineText,
29
+ isTextualMimeType,
24
30
  type ActionContext,
25
31
  type ActionResult,
26
32
  ConnectorRuntime,
@@ -129,18 +135,6 @@ const EXPORT_MIME_TYPES: Record<string, string> = {
129
135
  'application/vnd.google-apps.script': 'application/vnd.google-apps.script+json',
130
136
  };
131
137
 
132
- /** MIME types we will inline as `payload_text` when they are not Google-native. */
133
- const TEXTUAL_MIME_TYPES = new Set([
134
- 'application/json',
135
- 'application/xml',
136
- 'application/x-yaml',
137
- 'application/yaml',
138
- 'application/javascript',
139
- 'application/typescript',
140
- 'application/sql',
141
- 'application/x-sh',
142
- ]);
143
-
144
138
  /**
145
139
  * Cap on text inlined into `payload_text`.
146
140
  *
@@ -151,18 +145,6 @@ const TEXTUAL_MIME_TYPES = new Set([
151
145
  */
152
146
  const MAX_INLINE_TEXT_BYTES = 256 * 1024;
153
147
 
154
- /**
155
- * Default and ceiling for the text `download_file` echoes back inline.
156
- *
157
- * Inlining is a convenience for the caller that wants to READ a small file
158
- * without a second fetch through the artifact's `download_url`. It is not the
159
- * transport: the attachment is published either way. The ceiling exists because
160
- * inline content lands in an agent's context verbatim, where a multi-megabyte
161
- * blob is worse than useless — the `download_url` is the path for anything big.
162
- */
163
- const DEFAULT_INLINE_CONTENT_BYTES = 256 * 1024;
164
- const MAX_INLINE_CONTENT_BYTES = 1024 * 1024;
165
-
166
148
  /**
167
149
  * Grace window subtracted from `last_sync_at` before deciding a file's content
168
150
  * is unchanged.
@@ -175,13 +157,6 @@ const MAX_INLINE_CONTENT_BYTES = 1024 * 1024;
175
157
  */
176
158
  const CONTENT_SKEW_GRACE_MS = 5 * 60 * 1000;
177
159
 
178
- /**
179
- * Ceiling on anything this connector pulls in one piece — Google's own hard cap
180
- * on `files.export` (requesting more returns a 403), reused as the `alt=media`
181
- * download ceiling so both content paths refuse at the same size.
182
- */
183
- const MAX_EXPORT_BYTES = 10 * 1024 * 1024;
184
-
185
160
  /** Field mask for files.list / changes.list. Drive v3 returns almost nothing without it. */
186
161
  const FILE_FIELDS =
187
162
  'id,name,mimeType,description,webViewLink,size,createdTime,modifiedTime,trashed,owners(emailAddress,displayName),lastModifyingUser(emailAddress,displayName),parents';
@@ -220,51 +195,6 @@ function isPageTokenRejection(status: number): boolean {
220
195
  return status === 404 || status === 410;
221
196
  }
222
197
 
223
- /**
224
- * Truncate encoded UTF-8 to at most `maxBytes` WITHOUT splitting a character.
225
- *
226
- * A plain `slice(0, maxBytes)` can cut mid-sequence, and the decoder turns the
227
- * orphaned bytes into U+FFFD — a garbage character that then gets stored and
228
- * embedded. Back off up to three bytes (the longest UTF-8 tail) until the slice
229
- * decodes cleanly, so a legitimate U+FFFD already in the source is preserved
230
- * while a manufactured one is impossible.
231
- */
232
- function decodeTruncated(encoded: Uint8Array, maxBytes: number): string {
233
- const strict = new TextDecoder('utf-8', { fatal: true });
234
- for (let end = maxBytes; end > maxBytes - 4 && end >= 0; end--) {
235
- try {
236
- return strict.decode(encoded.slice(0, end));
237
- } catch {
238
- // Slice ended mid-sequence — drop a byte and retry.
239
- }
240
- }
241
- // Unreachable: `encoded` always comes from TextEncoder, so one of the four
242
- // slices above lands on a character boundary. Returning lossily here would
243
- // manufacture the very U+FFFD this function exists to prevent.
244
- return '';
245
- }
246
-
247
- /**
248
- * Decode downloaded bytes as text and cut them to the inline budget.
249
- *
250
- * The decode comes FIRST because `decodeTruncated` requires well-formed UTF-8
251
- * (it hands back nothing rather than manufacture a U+FFFD), and a downloaded
252
- * file is not required to be any such thing — a latin-1 CSV would otherwise
253
- * inline as an empty string, the exact "looks like an empty file" outcome this
254
- * connector refuses everywhere else. Decoding lossily once and re-encoding
255
- * gives the truncator the input it documents, and makes a truncated file read
256
- * the same as the first page of an untruncated one.
257
- */
258
- function inlineText(
259
- bytes: Uint8Array,
260
- maxBytes: number
261
- ): { content: string; truncated: boolean } {
262
- const text = new TextDecoder('utf-8').decode(bytes);
263
- const encoded = new TextEncoder().encode(text);
264
- if (encoded.byteLength <= maxBytes) return { content: text, truncated: false };
265
- return { content: decodeTruncated(encoded, maxBytes), truncated: true };
266
- }
267
-
268
198
  function exportMimeTypeFor(mimeType: string | undefined): string | undefined {
269
199
  if (!mimeType) return undefined;
270
200
  return EXPORT_MIME_TYPES[mimeType];
@@ -274,12 +204,6 @@ function isGoogleNative(mimeType: string | undefined): boolean {
274
204
  return Boolean(mimeType?.startsWith('application/vnd.google-apps.'));
275
205
  }
276
206
 
277
- function isTextualMimeType(mimeType: string | undefined): boolean {
278
- if (!mimeType) return false;
279
- const base = mimeType.split(';')[0]!.trim().toLowerCase();
280
- return TEXTUAL_MIME_TYPES.has(base) || base.startsWith('text/');
281
- }
282
-
283
207
  /** Drive reports size as a decimal string, and omits it entirely for native files. */
284
208
  function parseSize(size: string | undefined): number | undefined {
285
209
  if (typeof size !== 'string' || size.length === 0) return undefined;
@@ -476,12 +400,7 @@ export default class GoogleDriveConnector extends ConnectorRuntime<
476
400
  type: 'string',
477
401
  description: 'Drive file ID to download.',
478
402
  },
479
- inline_max_bytes: {
480
- type: 'integer',
481
- minimum: 0,
482
- maximum: MAX_INLINE_CONTENT_BYTES,
483
- description: `Return text content inline when the file is at most this many bytes (default ${DEFAULT_INLINE_CONTENT_BYTES}, max ${MAX_INLINE_CONTENT_BYTES}). Binary files are never inlined. 0 disables inlining; the attachment is still published.`,
484
- },
403
+ inline_max_bytes: inlineMaxBytesSchema(),
485
404
  },
486
405
  },
487
406
  },
@@ -920,13 +839,7 @@ export default class GoogleDriveConnector extends ConnectorRuntime<
920
839
  const fileId = input.file_id as string;
921
840
  if (!fileId) return { success: false, error: 'file_id is required.' };
922
841
 
923
- const requestedInline = input.inline_max_bytes;
924
- const inlineMaxBytes = Math.min(
925
- typeof requestedInline === 'number' && Number.isFinite(requestedInline) && requestedInline >= 0
926
- ? requestedInline
927
- : DEFAULT_INLINE_CONTENT_BYTES,
928
- MAX_INLINE_CONTENT_BYTES
929
- );
842
+ const inlineMaxBytes = inlineContentBudget(input.inline_max_bytes);
930
843
 
931
844
  const file = await this.fetchFileMetadata(http, fileId);
932
845
  if (!file) {
@@ -939,23 +852,6 @@ export default class GoogleDriveConnector extends ConnectorRuntime<
939
852
  }
940
853
 
941
854
  const filename = file.name ?? file.id;
942
- // `kind` is deliberately omitted: the gateway infers it from the media type
943
- // (`inferKindFromMime`), so there is one rule rather than two that can
944
- // disagree about what counts as an image.
945
- const attachment = {
946
- filename,
947
- mime_type: fetched.contentType,
948
- data: fetched.bytes.toString('base64'),
949
- size_bytes: fetched.bytes.length,
950
- };
951
-
952
- // Text is TRUNCATED to the inline budget rather than withheld: an agent
953
- // peeking at a large log or CSV is better served by its first page than by
954
- // being told to go fetch a URL. The attachment always carries the whole
955
- // file, so truncating here loses nothing.
956
- const textual =
957
- fetched.exportedAs !== undefined || isTextualMimeType(file.mimeType);
958
- const inline = inlineMaxBytes > 0 && textual ? inlineText(fetched.bytes, inlineMaxBytes) : undefined;
959
855
 
960
856
  return {
961
857
  success: true,
@@ -964,20 +860,22 @@ export default class GoogleDriveConnector extends ConnectorRuntime<
964
860
  name: filename,
965
861
  mime_type: file.mimeType ?? '',
966
862
  exported_as: fetched.exportedAs,
967
- size_bytes: fetched.bytes.length,
968
- attachments: [attachment],
969
- ...(inline
970
- ? {
971
- content: inline.content,
972
- content_truncated: inline.truncated,
973
- line_count:
974
- inline.content.length === 0 ? 0 : inline.content.split('\n').length,
975
- }
976
- : {
977
- content_omitted_reason: textual
978
- ? 'inlining disabled'
979
- : 'file is binary; fetch it through the attachment download_url',
980
- }),
863
+ ...fileDownloadOutput({
864
+ bytes: fetched.bytes,
865
+ filename,
866
+ mimeType: fetched.contentType,
867
+ inlineMaxBytes,
868
+ // Always decide textuality from Drive's DECLARED `file.mimeType`,
869
+ // never from `fetched.contentType`: the latter is the alt=media
870
+ // response header, which Drive routinely serves as
871
+ // `application/octet-stream` even for a text file. Letting the
872
+ // default rule read `contentType` would silently stop inlining those.
873
+ // An Apps Script exports as `...script+json`, which no generic
874
+ // media-type rule reads as text; the other exports already land on a
875
+ // `text/*` type and need no override.
876
+ textual:
877
+ fetched.exportedAs !== undefined || isTextualMimeType(file.mimeType),
878
+ }),
981
879
  },
982
880
  };
983
881
  }
@@ -1031,19 +929,12 @@ export default class GoogleDriveConnector extends ConnectorRuntime<
1031
929
  const request = this.contentRequest(file);
1032
930
  if (!request.ok) return request;
1033
931
 
1034
- // Refuse before fetching. The isolate buffers the whole body, then base64s
1035
- // it to cross the host boundary at 4/3 the size, so an unbounded download
1036
- // is an out-of-memory kill rather than an error the caller can read.
1037
- // MAX_EXPORT_BYTES sits above the gateway's own attachment cap on purpose:
1038
- // the gateway stays the authority on what is too big to store, and this
1039
- // only stops what cannot physically make the trip.
1040
- const declaredSize = parseSize(file.size);
1041
- if (declaredSize !== undefined && declaredSize > MAX_EXPORT_BYTES) {
1042
- return {
1043
- ok: false,
1044
- error: `File ${file.name ?? file.id} is ${declaredSize} bytes, above the ${MAX_EXPORT_BYTES}-byte download limit.`,
1045
- };
1046
- }
932
+ // Refuse before fetching, so a 2 GB file costs nothing. The shared ceiling
933
+ // (MAX_CONNECTOR_DOWNLOAD_BYTES, rationale there) happens to coincide with
934
+ // Google's own hard cap on `files.export` — requesting more returns a 403 —
935
+ // so both content paths refuse at the size Drive refuses at anyway.
936
+ const declaredTooBig = downloadSizeError(parseSize(file.size), file.name ?? file.id);
937
+ if (declaredTooBig) return { ok: false, error: declaredTooBig };
1047
938
 
1048
939
  const response = await http.raw(request.url);
1049
940
  if (!response.ok) {
@@ -1054,14 +945,10 @@ export default class GoogleDriveConnector extends ConnectorRuntime<
1054
945
  }
1055
946
 
1056
947
  const bytes = Buffer.from(await response.arrayBuffer());
1057
- if (bytes.length > MAX_EXPORT_BYTES) {
1058
- // Drive omits `size` for native docs, so the export path only learns the
1059
- // real size here. Same refusal, after the fact.
1060
- return {
1061
- ok: false,
1062
- error: `File ${file.name ?? file.id} returned ${bytes.length} bytes, above the ${MAX_EXPORT_BYTES}-byte download limit.`,
1063
- };
1064
- }
948
+ // Drive omits `size` for native docs, so the export path only learns the
949
+ // real size here. Same refusal, after the fact.
950
+ const receivedTooBig = downloadSizeError(bytes.length, file.name ?? file.id);
951
+ if (receivedTooBig) return { ok: false, error: receivedTooBig };
1065
952
  if (bytes.length === 0) {
1066
953
  return { ok: false, error: `Drive file ${file.name ?? file.id} is empty.` };
1067
954
  }
@@ -1121,15 +1008,13 @@ export default class GoogleDriveConnector extends ConnectorRuntime<
1121
1008
  }
1122
1009
 
1123
1010
  const raw = await response.text();
1124
- const encoded = new TextEncoder().encode(raw);
1125
- const truncated = encoded.byteLength > maxBytes;
1126
- const text = truncated ? decodeTruncated(encoded, maxBytes) : raw;
1011
+ const { content: text, truncated } = inlineText(raw, maxBytes);
1127
1012
 
1128
1013
  return {
1129
1014
  ok: true,
1130
1015
  text,
1131
1016
  truncated,
1132
- byteCount: encoded.byteLength,
1017
+ byteCount: Buffer.byteLength(raw, 'utf8'),
1133
1018
  ...(exportMime ? { exportedAs: exportMime } : {}),
1134
1019
  };
1135
1020
  }
@@ -6,6 +6,10 @@
6
6
  */
7
7
 
8
8
  import {
9
+ downloadSizeError,
10
+ fileDownloadOutput,
11
+ inlineContentBudget,
12
+ inlineMaxBytesSchema,
9
13
  type ActionContext,
10
14
  type ActionResult,
11
15
  ConnectorRuntime,
@@ -403,6 +407,38 @@ export default class GmailConnector extends ConnectorRuntime<GmailCheckpoint, Gm
403
407
  },
404
408
  },
405
409
  },
410
+ download_attachment: {
411
+ key: 'download_attachment',
412
+ kind: 'read',
413
+ name: 'Download Attachment',
414
+ description:
415
+ 'Download one attachment from a Gmail message. The bytes are published as an attachment with a `download_url` a device can fetch, and small text files are ALSO returned inline as `content`. Get `attachment_id` from `get_thread`, which lists each message\'s attachments.',
416
+ requiresApproval: false,
417
+ requiredScopes: ['https://www.googleapis.com/auth/gmail.readonly'],
418
+ inputSchema: {
419
+ type: 'object',
420
+ required: ['message_id', 'attachment_id'],
421
+ properties: {
422
+ message_id: {
423
+ type: 'string',
424
+ description: 'Message ID the attachment belongs to (from get_thread).',
425
+ },
426
+ attachment_id: {
427
+ type: 'string',
428
+ description: 'Attachment ID from get_thread. Gmail re-issues these per fetch, so use one from a recent get_thread rather than a stored copy.',
429
+ },
430
+ filename: {
431
+ type: 'string',
432
+ description: 'Name to publish the attachment under. Pass the filename get_thread reported for this attachment; nothing looks it up for you, so omitting it names the file after the attachment ID.',
433
+ },
434
+ mime_type: {
435
+ type: 'string',
436
+ description: 'Media type of the bytes. Pass the type get_thread reported for this attachment; nothing looks it up for you, so omitting it falls back to application/octet-stream, which also stops a text file being returned inline.',
437
+ },
438
+ inline_max_bytes: inlineMaxBytesSchema(),
439
+ },
440
+ },
441
+ },
406
442
  },
407
443
  };
408
444
 
@@ -585,6 +621,8 @@ export default class GmailConnector extends ConnectorRuntime<GmailCheckpoint, Gm
585
621
  return await this.searchEmails(http, ctx.input);
586
622
  case 'get_thread':
587
623
  return await this.getThread(http, ctx.input);
624
+ case 'download_attachment':
625
+ return await this.downloadAttachment(http, ctx.input);
588
626
  default:
589
627
  return { success: false, error: `Unknown action: ${ctx.actionKey}` };
590
628
  }
@@ -981,6 +1019,11 @@ export default class GmailConnector extends ConnectorRuntime<GmailCheckpoint, Gm
981
1019
  received_at: Number.isFinite(Number(msg.internalDate)) ? new Date(Number(msg.internalDate)).toISOString() : null,
982
1020
  snippet: msg.snippet,
983
1021
  body: await this.extractBody(msg.payload, http, msg.id),
1022
+ // Without this an agent can see that a mail HAS an attachment and
1023
+ // still have no way to name it: `attachment_id` exists nowhere else in
1024
+ // the connector's output, and download_attachment cannot be called
1025
+ // without one.
1026
+ attachments: this.collectAttachments(msg.payload),
984
1027
  });
985
1028
  }
986
1029
 
@@ -1173,6 +1216,112 @@ export default class GmailConnector extends ConnectorRuntime<GmailCheckpoint, Gm
1173
1216
 
1174
1217
  private readonly emailBodyConverter = createEmailBodyConverter();
1175
1218
 
1219
+ /**
1220
+ * List a message's attachment parts so an agent can name one.
1221
+ *
1222
+ * Gmail models an attachment as a leaf MIME part carrying a `filename` and a
1223
+ * `body.attachmentId`. The walk mirrors `extractBody`'s, but keeps exactly
1224
+ * what that one discards: a part with a filename is skipped there as "not
1225
+ * body text", which is precisely what makes it an attachment here.
1226
+ *
1227
+ * Inline parts (an embedded signature image) are included: they are real
1228
+ * bytes a caller may want, and Gmail does not mark them differently enough
1229
+ * to filter on without also dropping legitimate attachments.
1230
+ */
1231
+ private collectAttachments(
1232
+ payload: GmailMessagePayload
1233
+ ): Array<{ attachment_id: string; filename: string; mime_type: string; size_bytes: number }> {
1234
+ const found: Array<{
1235
+ attachment_id: string;
1236
+ filename: string;
1237
+ mime_type: string;
1238
+ size_bytes: number;
1239
+ }> = [];
1240
+ const walk = (part: GmailMessagePayload): void => {
1241
+ if (part.body?.attachmentId && part.filename) {
1242
+ found.push({
1243
+ attachment_id: part.body.attachmentId,
1244
+ filename: part.filename,
1245
+ mime_type: part.mimeType,
1246
+ size_bytes: part.body.size ?? 0,
1247
+ });
1248
+ }
1249
+ for (const child of part.parts ?? []) walk(child);
1250
+ };
1251
+ walk(payload);
1252
+ return found;
1253
+ }
1254
+
1255
+ /**
1256
+ * Download one attachment's bytes and publish them.
1257
+ *
1258
+ * Gmail returns the bytes base64url-encoded inside a JSON envelope rather
1259
+ * than as a body, and carries no filename or media type on that response —
1260
+ * both live on the MIME part, which is why `get_thread` reports them and why
1261
+ * they can be passed back in here.
1262
+ */
1263
+ private async downloadAttachment(
1264
+ http: HttpClient,
1265
+ input: Record<string, unknown>
1266
+ ): Promise<ActionResult> {
1267
+ const messageId = input.message_id as string;
1268
+ const attachmentId = input.attachment_id as string;
1269
+ if (!messageId) return { success: false, error: 'message_id is required.' };
1270
+ if (!attachmentId) return { success: false, error: 'attachment_id is required.' };
1271
+
1272
+ const response = await http.raw(
1273
+ `${this.BASE_URL}/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}`
1274
+ );
1275
+ if (!response.ok) {
1276
+ return {
1277
+ success: false,
1278
+ error: `Gmail attachment error (${response.status}): ${await response.text()}`,
1279
+ };
1280
+ }
1281
+
1282
+ const envelope = (await response.json()) as { data?: string; size?: number };
1283
+ const filename = (input.filename as string) || attachmentId;
1284
+ const mimeType = (input.mime_type as string) || 'application/octet-stream';
1285
+
1286
+ // Gmail has no size endpoint, so the base64 string is already in hand by
1287
+ // the time the declared size can be read. Refusing here still keeps the
1288
+ // decoded bytes and the base64 copy `fileDownloadOutput` re-encodes from
1289
+ // ever existing alongside it — three copies of the file is the OOM.
1290
+ const declaredTooBig = downloadSizeError(envelope.size, filename);
1291
+ if (declaredTooBig) return { success: false, error: declaredTooBig };
1292
+
1293
+ if (!envelope.data) {
1294
+ return { success: false, error: `Gmail attachment ${filename} returned no data.` };
1295
+ }
1296
+
1297
+ // Gmail uses base64URL (RFC 4648 §5); Buffer's 'base64' decoder accepts
1298
+ // both alphabets, so no translation is needed.
1299
+ const bytes = Buffer.from(envelope.data, 'base64');
1300
+ if (bytes.length === 0) {
1301
+ return { success: false, error: `Gmail attachment ${filename} is empty.` };
1302
+ }
1303
+ // Gmail's `size` is the decoded length, but it is advisory: an attachment
1304
+ // that omits it only reveals its real size here.
1305
+ const receivedTooBig = downloadSizeError(bytes.length, filename);
1306
+ if (receivedTooBig) return { success: false, error: receivedTooBig };
1307
+
1308
+ return {
1309
+ success: true,
1310
+ output: {
1311
+ message_id: messageId,
1312
+ attachment_id: attachmentId,
1313
+ name: filename,
1314
+ mime_type: mimeType,
1315
+ ...fileDownloadOutput({
1316
+ bytes,
1317
+ filename,
1318
+ mimeType,
1319
+ inlineMaxBytes: inlineContentBudget(input.inline_max_bytes),
1320
+ }),
1321
+ },
1322
+ };
1323
+ }
1324
+
1176
1325
  private async extractBody(
1177
1326
  payload: GmailMessagePayload,
1178
1327
  http: HttpClient,