@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
@@ -6,10 +6,16 @@
6
6
  */
7
7
 
8
8
  import {
9
+ type ActionContext,
10
+ type ActionResult,
9
11
  type RuntimeConnectorDefinition,
10
12
  ConnectorRuntime,
13
+ downloadSizeError,
11
14
  type EventEnvelope,
15
+ fileDownloadOutput,
12
16
  type HttpClient,
17
+ inlineContentBudget,
18
+ inlineMaxBytesSchema,
13
19
  paginateByCursor,
14
20
  requireBearerClient,
15
21
  type SyncContext,
@@ -20,6 +26,21 @@ import {
20
26
  // Microsoft Graph API types
21
27
  // ---------------------------------------------------------------------------
22
28
 
29
+ /**
30
+ * One `/messages/{id}/attachments` entry. `contentBytes` is present only on
31
+ * `#microsoft.graph.fileAttachment`; the reference and item subtypes carry a
32
+ * link or an embedded resource instead.
33
+ */
34
+ interface GraphAttachment {
35
+ id: string;
36
+ name?: string;
37
+ contentType?: string;
38
+ size?: number;
39
+ isInline?: boolean;
40
+ contentBytes?: string;
41
+ '@odata.type'?: string;
42
+ }
43
+
23
44
  interface GraphMessage {
24
45
  id: string;
25
46
  conversationId: string;
@@ -218,6 +239,51 @@ export default class MicrosoftOutlookConnector extends ConnectorRuntime {
218
239
  },
219
240
  },
220
241
  },
242
+ actions: {
243
+ list_attachments: {
244
+ key: 'list_attachments',
245
+ kind: 'read',
246
+ name: 'List Attachments',
247
+ description:
248
+ "List a message's attachments with their IDs, names, types and sizes. The feed only reports `has_attachments`, so this is how an agent learns what to download.",
249
+ requiresApproval: false,
250
+ requiredScopes: ['Mail.Read'],
251
+ inputSchema: {
252
+ type: 'object',
253
+ required: ['message_id'],
254
+ properties: {
255
+ message_id: {
256
+ type: 'string',
257
+ description: 'Message ID (the event\'s origin_id).',
258
+ },
259
+ },
260
+ },
261
+ },
262
+ download_attachment: {
263
+ key: 'download_attachment',
264
+ kind: 'read',
265
+ name: 'Download Attachment',
266
+ description:
267
+ 'Download one attachment from an Outlook 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 `list_attachments`.',
268
+ requiresApproval: false,
269
+ requiredScopes: ['Mail.Read'],
270
+ inputSchema: {
271
+ type: 'object',
272
+ required: ['message_id', 'attachment_id'],
273
+ properties: {
274
+ message_id: {
275
+ type: 'string',
276
+ description: 'Message ID the attachment belongs to.',
277
+ },
278
+ attachment_id: {
279
+ type: 'string',
280
+ description: 'Attachment ID from list_attachments.',
281
+ },
282
+ inline_max_bytes: inlineMaxBytesSchema(),
283
+ },
284
+ },
285
+ },
286
+ },
221
287
  };
222
288
 
223
289
  private readonly API_BASE = 'https://graph.microsoft.com/v1.0';
@@ -248,6 +314,133 @@ export default class MicrosoftOutlookConnector extends ConnectorRuntime {
248
314
  // -------------------------------------------------------------------------
249
315
  // execute
250
316
  // -------------------------------------------------------------------------
317
+
318
+ async execute(ctx: ActionContext): Promise<ActionResult> {
319
+ try {
320
+ const http = requireBearerClient(ctx.credentials, {
321
+ errorPrefix: 'Microsoft Graph API',
322
+ label: 'Microsoft Outlook',
323
+ });
324
+
325
+ switch (ctx.actionKey) {
326
+ case 'list_attachments':
327
+ return await this.listAttachments(http, ctx.input);
328
+ case 'download_attachment':
329
+ return await this.downloadAttachment(http, ctx.input);
330
+ default:
331
+ return { success: false, error: `Unknown action: ${ctx.actionKey}` };
332
+ }
333
+ } catch (error) {
334
+ return {
335
+ success: false,
336
+ error: error instanceof Error ? error.message : String(error),
337
+ };
338
+ }
339
+ }
340
+
341
+ /**
342
+ * List a message's attachments without their bytes.
343
+ *
344
+ * `$select` is load-bearing, not a micro-optimisation: Graph serialises
345
+ * `contentBytes` into the LIST response by default, so an unfiltered call on
346
+ * a mail with three 5 MB files returns ~20 MB of base64 the caller never
347
+ * asked for — which on the isolate lane is an out-of-memory kill.
348
+ *
349
+ * Reference attachments (a OneDrive link) and item attachments (an embedded
350
+ * mail) carry no `contentBytes` at all. `type` echoes the `@odata.type`
351
+ * annotation that marks which subtype each entry is, so a caller can usually
352
+ * see up front why `download_attachment` will refuse one. It is an annotation
353
+ * rather than a selected property, so treat it as advisory and empty when
354
+ * absent — the authoritative refusal comes from `download_attachment`, whose
355
+ * single-attachment GET is not `$select`ed and always carries the subtype.
356
+ */
357
+ private async listAttachments(
358
+ http: HttpClient,
359
+ input: Record<string, unknown>
360
+ ): Promise<ActionResult> {
361
+ const messageId = input.message_id as string;
362
+ if (!messageId) return { success: false, error: 'message_id is required.' };
363
+
364
+ const response = (await http.get(
365
+ `${this.API_BASE}/me/messages/${encodeURIComponent(messageId)}/attachments?$select=id,name,contentType,size,isInline`
366
+ )) as { value?: GraphAttachment[] };
367
+
368
+ return {
369
+ success: true,
370
+ output: {
371
+ message_id: messageId,
372
+ attachments: (response.value ?? []).map((attachment) => ({
373
+ attachment_id: attachment.id,
374
+ filename: attachment.name ?? attachment.id,
375
+ mime_type: attachment.contentType ?? 'application/octet-stream',
376
+ size_bytes: attachment.size ?? 0,
377
+ is_inline: Boolean(attachment.isInline),
378
+ type: attachment['@odata.type'] ?? '',
379
+ })),
380
+ },
381
+ };
382
+ }
383
+
384
+ /**
385
+ * Download one attachment's bytes and publish them.
386
+ *
387
+ * Graph returns the bytes base64 inside the attachment resource rather than
388
+ * as a body. The `$value` endpoint would hand back raw bytes, but it 404s for
389
+ * anything that is not a file attachment, so the JSON shape is used for both
390
+ * the bytes and the readable refusal.
391
+ */
392
+ private async downloadAttachment(
393
+ http: HttpClient,
394
+ input: Record<string, unknown>
395
+ ): Promise<ActionResult> {
396
+ const messageId = input.message_id as string;
397
+ const attachmentId = input.attachment_id as string;
398
+ if (!messageId) return { success: false, error: 'message_id is required.' };
399
+ if (!attachmentId) return { success: false, error: 'attachment_id is required.' };
400
+
401
+ const attachment = (await http.get(
402
+ `${this.API_BASE}/me/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}`
403
+ )) as GraphAttachment;
404
+
405
+ // Refuse on the DECLARED size before decoding, so the decoded bytes and the
406
+ // base64 copy re-encoded for the attachment never join the string in memory.
407
+ const declaredTooBig = downloadSizeError(attachment.size, attachment.name ?? attachmentId);
408
+ if (declaredTooBig) return { success: false, error: declaredTooBig };
409
+
410
+ if (!attachment.contentBytes) {
411
+ return {
412
+ success: false,
413
+ error: `Outlook attachment ${attachment.name ?? attachmentId} carries no bytes (${attachment['@odata.type'] ?? 'unknown type'}). Only file attachments can be downloaded; a reference attachment lives in OneDrive and an item attachment is an embedded message.`,
414
+ };
415
+ }
416
+
417
+ const bytes = Buffer.from(attachment.contentBytes, 'base64');
418
+ if (bytes.length === 0) {
419
+ return { success: false, error: `Outlook attachment ${attachment.name ?? attachmentId} is empty.` };
420
+ }
421
+ const receivedTooBig = downloadSizeError(bytes.length, attachment.name ?? attachmentId);
422
+ if (receivedTooBig) return { success: false, error: receivedTooBig };
423
+
424
+ const filename = attachment.name ?? attachmentId;
425
+ const mimeType = attachment.contentType ?? 'application/octet-stream';
426
+
427
+ return {
428
+ success: true,
429
+ output: {
430
+ message_id: messageId,
431
+ attachment_id: attachmentId,
432
+ name: filename,
433
+ mime_type: mimeType,
434
+ ...fileDownloadOutput({
435
+ bytes,
436
+ filename,
437
+ mimeType,
438
+ inlineMaxBytes: inlineContentBudget(input.inline_max_bytes),
439
+ }),
440
+ },
441
+ };
442
+ }
443
+
251
444
  // -------------------------------------------------------------------------
252
445
  // Feed: messages
253
446
  // -------------------------------------------------------------------------
@@ -13,6 +13,7 @@ import type {
13
13
  AclSourceDef,
14
14
  ChannelReadIdentity,
15
15
  } from '@lobu/connector-sdk';
16
+ import type { ChatUserIdentity } from './chat-user-identity.js';
16
17
  import type { ConnectorIdentityModule } from './connector-identity-module.js';
17
18
 
18
19
  /** Connector-owned identity namespaces (not SDK-global). */
@@ -125,6 +126,25 @@ export const slackChannelReadIdentity: ChannelReadIdentity = {
125
126
  },
126
127
  };
127
128
 
129
+ /**
130
+ * Slack's chat-sender identity model — how an inbound message's sender maps to
131
+ * the `slack_user_id` a Slack sign-in stamped. Shares `normalizeSlackUserId`
132
+ * with the writer so the key matches byte-for-byte.
133
+ *
134
+ * The team id is REQUIRED: `buildUserKey` returns null without it rather than
135
+ * falling back to a bare `U…`. Two workspaces can legitimately contain the same
136
+ * bare id, and this link authorizes approvals and agent re-binding, so an
137
+ * unscoped key would be a mis-grant.
138
+ */
139
+ export const slackChatUserIdentity: ChatUserIdentity = {
140
+ platform: 'slack',
141
+ providerId: 'slack',
142
+ namespace: SLACK_IDENTITY.USER_ID,
143
+ buildUserKey(teamId, platformUserId) {
144
+ return normalizeSlackUserId(teamId, platformUserId);
145
+ },
146
+ };
147
+
128
148
  /** A Slack channel and the (bare `U…`) ids of its members. */
129
149
  export interface SlackChannelInput {
130
150
  /** Bare Slack channel id (`C…` / `G…`). */
@@ -97,12 +97,20 @@ async function getCredentialsToken(contextName) {
97
97
  return null;
98
98
  if (!credentialNeedsRefresh(creds))
99
99
  return creds.accessToken;
100
+ // Say why before dropping: a silent clear surfaces downstream as
101
+ // "Not logged in", sending users to debug auth instead of re-running login.
102
+ // Fires once per process — the clear poisons the cache to null, so later
103
+ // getToken() calls take the `!creds` path above without repeating this.
104
+ const staleNote = `\n Saved login for "${contextName ?? DEFAULT_CONTEXT_NAME}" expired and ` +
105
+ `could not be refreshed. Run \`lobu login\` to sign in again.\n`;
100
106
  if (!credentialCanRefresh(creds)) {
107
+ process.stderr.write(staleNote);
101
108
  await clearCredentials(contextName);
102
109
  return null;
103
110
  }
104
111
  const refreshed = await refreshCredentials(creds, contextName);
105
112
  if (!refreshed) {
113
+ process.stderr.write(staleNote);
106
114
  await clearCredentials(contextName);
107
115
  return null;
108
116
  }
@@ -7,4 +7,12 @@
7
7
  * overwrite earlier ones (matching `dotenv` semantics).
8
8
  */
9
9
  export declare function parseEnvContent(content: string): Record<string, string>;
10
+ /**
11
+ * Read the project `.env` in `cwd`, falling back to {} when the file is
12
+ * absent. Shell environment always wins — callers check `process.env` first
13
+ * and use this only as the project-local fallback.
14
+ */
15
+ export declare function readProjectEnvFile(cwd: string): Promise<Record<string, string>>;
16
+ /** Read one variable from the project `.env` in `cwd` ("" when absent). */
17
+ export declare function readProjectEnvValue(cwd: string, key: string): Promise<string>;
10
18
  //# sourceMappingURL=env-file.d.ts.map
@@ -1,3 +1,5 @@
1
+ import { readFile } from "node:fs/promises";
2
+ import { join } from "node:path";
1
3
  /**
2
4
  * Minimal .env file parser shared across Lobu CLIs.
3
5
  *
@@ -28,4 +30,23 @@ export function parseEnvContent(content) {
28
30
  }
29
31
  return vars;
30
32
  }
33
+ /**
34
+ * Read the project `.env` in `cwd`, falling back to {} when the file is
35
+ * absent. Shell environment always wins — callers check `process.env` first
36
+ * and use this only as the project-local fallback.
37
+ */
38
+ export async function readProjectEnvFile(cwd) {
39
+ try {
40
+ const raw = await readFile(join(cwd, ".env"), "utf-8");
41
+ return parseEnvContent(raw);
42
+ }
43
+ catch {
44
+ return {};
45
+ }
46
+ }
47
+ /** Read one variable from the project `.env` in `cwd` ("" when absent). */
48
+ export async function readProjectEnvValue(cwd, key) {
49
+ const env = await readProjectEnvFile(cwd);
50
+ return env[key]?.trim() ?? "";
51
+ }
31
52
  //# sourceMappingURL=env-file.js.map
@@ -5,7 +5,7 @@
5
5
  "server": "dist/server.bundle.mjs",
6
6
  "embeddingsServer": "dist/embeddings-server.mjs"
7
7
  },
8
- "version": "20.0.1",
8
+ "version": "20.1.0",
9
9
  "verify": "dist/verify.mjs"
10
10
  },
11
11
  "device": {
@@ -16,7 +16,7 @@
16
16
  "connector": "node_modules/@lobu/cli/dist/commands/connector.js",
17
17
  "worker": "node_modules/@lobu/connector-worker/dist/bin.js"
18
18
  },
19
- "version": "20.0.1",
19
+ "version": "20.1.0",
20
20
  "verify": "dist/verify.mjs"
21
21
  },
22
22
  "postgres": {
@@ -24,7 +24,7 @@
24
24
  "entries": {
25
25
  "postgres": "dist/index.mjs"
26
26
  },
27
- "version": "20.0.1",
27
+ "version": "20.1.0",
28
28
  "verify": "dist/verify.mjs"
29
29
  },
30
30
  "embeddings": {
@@ -32,7 +32,7 @@
32
32
  "entries": {
33
33
  "embeddings": "dist/embeddings.js"
34
34
  },
35
- "version": "20.0.1",
35
+ "version": "20.1.0",
36
36
  "verify": "dist/verify.mjs"
37
37
  }
38
38
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lobu/cli",
3
- "version": "20.0.1",
3
+ "version": "20.1.0",
4
4
  "description": "CLI for deploying and managing AI agents on Lobu",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -0,0 +1,97 @@
1
+ /**
2
+ * Portable connector file OUTPUT — the symmetric counterpart to `file-input.ts`.
3
+ *
4
+ * A connector hands bytes back by emitting an `attachments` array. The gateway
5
+ * strips the bytes into the artifact store and rewrites each entry to an
6
+ * `artifact_id` plus a signed `download_url`, so the bytes reach a device or a
7
+ * sandbox over HTTP instead of through the model's context. A connector that
8
+ * returns file content any other way (a bare base64 string, a provider URL that
9
+ * needs the provider's credential) cannot be downloaded by an agent at all.
10
+ *
11
+ * The emit step is identical for every provider — only "which URL holds the
12
+ * bytes" differs — and getting any part of it subtly wrong is silent: a
13
+ * mis-sliced UTF-8 string stores a manufactured U+FFFD, and a missing size
14
+ * guard is an out-of-memory kill rather than a readable error. Hence one copy.
15
+ */
16
+ /**
17
+ * Ceiling on a single download, enforced by the connector.
18
+ *
19
+ * This sits ABOVE the gateway's own 8 MiB attachment cap on purpose: the
20
+ * gateway decides what is too big to STORE and reports it as
21
+ * `attachments_rejected`, while this decides what is too big to hold in memory.
22
+ * A connector isolate buffers the whole body and then base64s it at 4/3 the
23
+ * size, so an unbounded download is an OOM kill, not a rejected attachment.
24
+ */
25
+ export declare const MAX_CONNECTOR_DOWNLOAD_BYTES: number;
26
+ /** Inline text budget when the caller does not ask for one. */
27
+ export declare const DEFAULT_INLINE_CONTENT_BYTES: number;
28
+ /** Hard ceiling on inline text, whatever the caller asks for. */
29
+ export declare const MAX_INLINE_CONTENT_BYTES: number;
30
+ /** True when a media type's bytes are meaningfully readable as text. */
31
+ export declare function isTextualMimeType(mimeType: string | undefined): boolean;
32
+ /**
33
+ * Clamp a caller-supplied `inline_max_bytes` into the allowed range.
34
+ *
35
+ * A non-number, a negative, or an absent value all fall back to the default;
36
+ * `0` is honoured as "do not inline" rather than treated as absent, which is
37
+ * why this cannot be written with `??`.
38
+ */
39
+ export declare function inlineContentBudget(requested: unknown): number;
40
+ /**
41
+ * Refuse an oversized download and say why, or return null to proceed.
42
+ *
43
+ * Call it twice: once with the size the provider DECLARES and once with the
44
+ * bytes actually received. Neither call is redundant — Drive omits the declared
45
+ * size for its native documents, while Gmail and Graph only reveal it in the
46
+ * same response that carries the bytes.
47
+ */
48
+ export declare function downloadSizeError(size: number | undefined, label: string): string | null;
49
+ /**
50
+ * Decode downloaded bytes as text and cut them to the inline budget.
51
+ *
52
+ * The decode comes FIRST because `decodeTruncated` requires well-formed UTF-8
53
+ * (it hands back nothing rather than manufacture a U+FFFD), and a downloaded
54
+ * file is not required to be any such thing — a latin-1 CSV would otherwise
55
+ * inline as an empty string, the exact "looks like an empty file" outcome this
56
+ * module refuses everywhere else. Decoding lossily once and re-encoding gives
57
+ * the truncator the input it documents, and makes a truncated file read the
58
+ * same as the first page of an untruncated one.
59
+ */
60
+ export declare function inlineText(source: Uint8Array | string, maxBytes: number): {
61
+ content: string;
62
+ truncated: boolean;
63
+ };
64
+ export interface FileDownloadOptions {
65
+ bytes: Uint8Array;
66
+ filename: string;
67
+ mimeType: string;
68
+ /**
69
+ * Inline text budget. Omit for the default; re-clamped here either way, so
70
+ * the ceiling holds even for a caller that skipped {@link inlineContentBudget}.
71
+ */
72
+ inlineMaxBytes?: number;
73
+ /**
74
+ * Force the textual decision instead of deriving it from `mimeType`. Drive
75
+ * needs this: a Google Doc's own media type is not textual, but the bytes it
76
+ * exported are.
77
+ */
78
+ textual?: boolean;
79
+ }
80
+ /**
81
+ * Build the action output for one downloaded file.
82
+ *
83
+ * The attachment always carries the WHOLE file; inline text is a convenience
84
+ * head, truncated rather than withheld, so a caller peeking at a large CSV gets
85
+ * its first page instead of being told to go fetch a URL.
86
+ *
87
+ * `kind` is deliberately omitted from the attachment: the gateway infers it
88
+ * from the media type (`inferKindFromMime`), so there is one rule rather than
89
+ * two that can disagree about what counts as an image.
90
+ */
91
+ export declare function fileDownloadOutput(params: FileDownloadOptions): Record<string, unknown>;
92
+ /**
93
+ * The shared `inline_max_bytes` field, so every connector's download action
94
+ * documents the same budget with the same words.
95
+ */
96
+ export declare function inlineMaxBytesSchema(): Record<string, unknown>;
97
+ //# sourceMappingURL=file-output.d.ts.map
@@ -0,0 +1,176 @@
1
+ /**
2
+ * Portable connector file OUTPUT — the symmetric counterpart to `file-input.ts`.
3
+ *
4
+ * A connector hands bytes back by emitting an `attachments` array. The gateway
5
+ * strips the bytes into the artifact store and rewrites each entry to an
6
+ * `artifact_id` plus a signed `download_url`, so the bytes reach a device or a
7
+ * sandbox over HTTP instead of through the model's context. A connector that
8
+ * returns file content any other way (a bare base64 string, a provider URL that
9
+ * needs the provider's credential) cannot be downloaded by an agent at all.
10
+ *
11
+ * The emit step is identical for every provider — only "which URL holds the
12
+ * bytes" differs — and getting any part of it subtly wrong is silent: a
13
+ * mis-sliced UTF-8 string stores a manufactured U+FFFD, and a missing size
14
+ * guard is an out-of-memory kill rather than a readable error. Hence one copy.
15
+ */
16
+ /**
17
+ * Ceiling on a single download, enforced by the connector.
18
+ *
19
+ * This sits ABOVE the gateway's own 8 MiB attachment cap on purpose: the
20
+ * gateway decides what is too big to STORE and reports it as
21
+ * `attachments_rejected`, while this decides what is too big to hold in memory.
22
+ * A connector isolate buffers the whole body and then base64s it at 4/3 the
23
+ * size, so an unbounded download is an OOM kill, not a rejected attachment.
24
+ */
25
+ export const MAX_CONNECTOR_DOWNLOAD_BYTES = 10 * 1024 * 1024;
26
+ /** Inline text budget when the caller does not ask for one. */
27
+ export const DEFAULT_INLINE_CONTENT_BYTES = 256 * 1024;
28
+ /** Hard ceiling on inline text, whatever the caller asks for. */
29
+ export const MAX_INLINE_CONTENT_BYTES = 1024 * 1024;
30
+ /** Media types that are text even though they are not `text/*`. */
31
+ const TEXTUAL_MIME_TYPES = new Set([
32
+ 'application/json',
33
+ 'application/xml',
34
+ 'application/javascript',
35
+ 'application/x-javascript',
36
+ 'application/x-yaml',
37
+ 'application/yaml',
38
+ 'application/typescript',
39
+ 'application/rtf',
40
+ 'application/x-sh',
41
+ 'application/sql',
42
+ 'image/svg+xml',
43
+ ]);
44
+ /** True when a media type's bytes are meaningfully readable as text. */
45
+ export function isTextualMimeType(mimeType) {
46
+ if (!mimeType)
47
+ return false;
48
+ const base = mimeType.split(';')[0]?.trim().toLowerCase() ?? '';
49
+ return TEXTUAL_MIME_TYPES.has(base) || base.startsWith('text/');
50
+ }
51
+ /**
52
+ * Clamp a caller-supplied `inline_max_bytes` into the allowed range.
53
+ *
54
+ * A non-number, a negative, or an absent value all fall back to the default;
55
+ * `0` is honoured as "do not inline" rather than treated as absent, which is
56
+ * why this cannot be written with `??`.
57
+ */
58
+ export function inlineContentBudget(requested) {
59
+ const valid = typeof requested === 'number' && Number.isFinite(requested) && requested >= 0;
60
+ return Math.min(valid ? requested : DEFAULT_INLINE_CONTENT_BYTES, MAX_INLINE_CONTENT_BYTES);
61
+ }
62
+ /**
63
+ * Refuse an oversized download and say why, or return null to proceed.
64
+ *
65
+ * Call it twice: once with the size the provider DECLARES and once with the
66
+ * bytes actually received. Neither call is redundant — Drive omits the declared
67
+ * size for its native documents, while Gmail and Graph only reveal it in the
68
+ * same response that carries the bytes.
69
+ */
70
+ export function downloadSizeError(size, label) {
71
+ if (size === undefined || size <= MAX_CONNECTOR_DOWNLOAD_BYTES)
72
+ return null;
73
+ return `File ${label} is ${size} bytes, above the ${MAX_CONNECTOR_DOWNLOAD_BYTES}-byte download limit. Fetch it directly from the provider instead.`;
74
+ }
75
+ /**
76
+ * Cut already-valid UTF-8 to a byte budget without manufacturing a U+FFFD.
77
+ *
78
+ * A plain `slice(0, maxBytes)` can cut mid-sequence, and the decoder turns the
79
+ * orphaned bytes into U+FFFD — a garbage character that then gets stored and
80
+ * embedded. Back off up to three bytes (the longest UTF-8 tail) until the slice
81
+ * decodes cleanly, so a legitimate U+FFFD already in the source is preserved
82
+ * while a manufactured one is impossible.
83
+ */
84
+ function decodeTruncated(encoded, maxBytes) {
85
+ const strict = new TextDecoder('utf-8', { fatal: true });
86
+ for (let end = maxBytes; end > maxBytes - 4 && end >= 0; end--) {
87
+ try {
88
+ return strict.decode(encoded.slice(0, end));
89
+ }
90
+ catch {
91
+ // Slice ended mid-sequence — drop a byte and retry.
92
+ }
93
+ }
94
+ // Unreachable: `encoded` always comes from TextEncoder, so one of the four
95
+ // slices above lands on a character boundary. Returning lossily here would
96
+ // manufacture the very U+FFFD this function exists to prevent.
97
+ return '';
98
+ }
99
+ /**
100
+ * Decode downloaded bytes as text and cut them to the inline budget.
101
+ *
102
+ * The decode comes FIRST because `decodeTruncated` requires well-formed UTF-8
103
+ * (it hands back nothing rather than manufacture a U+FFFD), and a downloaded
104
+ * file is not required to be any such thing — a latin-1 CSV would otherwise
105
+ * inline as an empty string, the exact "looks like an empty file" outcome this
106
+ * module refuses everywhere else. Decoding lossily once and re-encoding gives
107
+ * the truncator the input it documents, and makes a truncated file read the
108
+ * same as the first page of an untruncated one.
109
+ */
110
+ export function inlineText(source, maxBytes) {
111
+ // A caller that already decoded (a feed reading `response.text()`) passes the
112
+ // string: re-encoding it only to decode it back here is a full extra copy of
113
+ // every file on the ingest path, and it is a no-op — `response.text()` has
114
+ // already substituted U+FFFD for anything undecodable, and that round-trips
115
+ // cleanly.
116
+ const text = typeof source === 'string' ? source : new TextDecoder('utf-8').decode(source);
117
+ const encoded = new TextEncoder().encode(text);
118
+ if (encoded.byteLength <= maxBytes)
119
+ return { content: text, truncated: false };
120
+ return { content: decodeTruncated(encoded, maxBytes), truncated: true };
121
+ }
122
+ /**
123
+ * Build the action output for one downloaded file.
124
+ *
125
+ * The attachment always carries the WHOLE file; inline text is a convenience
126
+ * head, truncated rather than withheld, so a caller peeking at a large CSV gets
127
+ * its first page instead of being told to go fetch a URL.
128
+ *
129
+ * `kind` is deliberately omitted from the attachment: the gateway infers it
130
+ * from the media type (`inferKindFromMime`), so there is one rule rather than
131
+ * two that can disagree about what counts as an image.
132
+ */
133
+ export function fileDownloadOutput(params) {
134
+ const { bytes, filename, mimeType } = params;
135
+ const budget = inlineContentBudget(params.inlineMaxBytes);
136
+ const textual = params.textual ?? isTextualMimeType(mimeType);
137
+ const inline = budget > 0 && textual ? inlineText(bytes, budget) : undefined;
138
+ return {
139
+ size_bytes: bytes.length,
140
+ attachments: [
141
+ {
142
+ filename,
143
+ mime_type: mimeType,
144
+ // A VIEW over the same memory, not `Buffer.from(bytes)` — that copies
145
+ // the whole payload, and at the 10 MiB ceiling an extra full copy is
146
+ // exactly the allocation this module's callers guard against.
147
+ data: Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64'),
148
+ size_bytes: bytes.length,
149
+ },
150
+ ],
151
+ ...(inline
152
+ ? {
153
+ content: inline.content,
154
+ content_truncated: inline.truncated,
155
+ line_count: inline.content.length === 0 ? 0 : inline.content.split('\n').length,
156
+ }
157
+ : {
158
+ content_omitted_reason: textual
159
+ ? 'inlining disabled'
160
+ : 'file is binary; fetch it through the attachment download_url',
161
+ }),
162
+ };
163
+ }
164
+ /**
165
+ * The shared `inline_max_bytes` field, so every connector's download action
166
+ * documents the same budget with the same words.
167
+ */
168
+ export function inlineMaxBytesSchema() {
169
+ return {
170
+ type: 'integer',
171
+ minimum: 0,
172
+ maximum: MAX_INLINE_CONTENT_BYTES,
173
+ 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.`,
174
+ };
175
+ }
176
+ //# sourceMappingURL=file-output.js.map
@@ -7,6 +7,8 @@ export { BridgeOnlyConnector, ConnectorRuntime, IntegrationConnector, } from './
7
7
  export { defineConnector } from './define-connector.js';
8
8
  export { fileInputSchema, MAX_CONNECTOR_FILE_BYTES } from './file-input.js';
9
9
  export type { ConnectorFile, FileInputOptions, FileReference } from './file-input.js';
10
+ export { DEFAULT_INLINE_CONTENT_BYTES, downloadSizeError, fileDownloadOutput, inlineContentBudget, inlineMaxBytesSchema, inlineText, isTextualMimeType, MAX_CONNECTOR_DOWNLOAD_BYTES, MAX_INLINE_CONTENT_BYTES, } from './file-output.js';
11
+ export type { FileDownloadOptions } from './file-output.js';
10
12
  export { canonicalDeviceManifestJson, defineDeviceConnector, serializeDeviceConnector, sortDeviceManifestJson, } from './device-manifest.js';
11
13
  export type { DeviceActionDefinition, DeviceConnectorDefinition, DeviceConnectorManifest, DeviceConnectorRuntimeInfo, DeviceConnectorSpec, DeviceFeedDefinition, DeviceManifestSchema, } from './device-manifest.js';
12
14
  import { validateEntityMetrics } from './metrics.js';
@@ -8,6 +8,7 @@ export { default as ky, HTTPError } from 'ky';
8
8
  export { BridgeOnlyConnector, ConnectorRuntime, IntegrationConnector, } from './connector-runtime.js';
9
9
  export { defineConnector } from './define-connector.js';
10
10
  export { fileInputSchema, MAX_CONNECTOR_FILE_BYTES } from './file-input.js';
11
+ export { DEFAULT_INLINE_CONTENT_BYTES, downloadSizeError, fileDownloadOutput, inlineContentBudget, inlineMaxBytesSchema, inlineText, isTextualMimeType, MAX_CONNECTOR_DOWNLOAD_BYTES, MAX_INLINE_CONTENT_BYTES, } from './file-output.js';
11
12
  export { canonicalDeviceManifestJson, defineDeviceConnector, serializeDeviceConnector, sortDeviceManifestJson, } from './device-manifest.js';
12
13
  import { validateEntityMetrics } from './metrics.js';
13
14
  export { validateEntityMetrics };
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lobu/connector-sdk",
3
- "version": "20.0.1",
3
+ "version": "20.1.0",
4
4
  "description": "Lobu memory SDK — build pluggable connectors for Lobu memory",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",