@vertesia/client 1.6.0-dev.20261019.172735Z → 1.7.0-dev.20261120.100641Z

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 (226) hide show
  1. package/lib/AccountApi.d.ts +2 -0
  2. package/lib/AccountApi.d.ts.map +1 -1
  3. package/lib/AccountApi.js +3 -0
  4. package/lib/AccountApi.js.map +1 -1
  5. package/lib/AccountRolesApi.d.ts +11 -0
  6. package/lib/AccountRolesApi.d.ts.map +1 -0
  7. package/lib/AccountRolesApi.js +22 -0
  8. package/lib/AccountRolesApi.js.map +1 -0
  9. package/lib/ApiKeysApi.d.ts +4 -7
  10. package/lib/ApiKeysApi.d.ts.map +1 -1
  11. package/lib/ApiKeysApi.js +5 -4
  12. package/lib/ApiKeysApi.js.map +1 -1
  13. package/lib/AppsApi.d.ts +18 -3
  14. package/lib/AppsApi.d.ts.map +1 -1
  15. package/lib/AppsApi.js +34 -4
  16. package/lib/AppsApi.js.map +1 -1
  17. package/lib/AuditTrailApi.d.ts +6 -1
  18. package/lib/AuditTrailApi.d.ts.map +1 -1
  19. package/lib/AuditTrailApi.js +8 -0
  20. package/lib/AuditTrailApi.js.map +1 -1
  21. package/lib/EnvironmentsApi.d.ts +2 -2
  22. package/lib/EnvironmentsApi.d.ts.map +1 -1
  23. package/lib/IamApi.d.ts +1 -1
  24. package/lib/IamApi.js +1 -1
  25. package/lib/InteractionCatalogApi.d.ts +19 -1
  26. package/lib/InteractionCatalogApi.d.ts.map +1 -1
  27. package/lib/InteractionCatalogApi.js +30 -0
  28. package/lib/InteractionCatalogApi.js.map +1 -1
  29. package/lib/InteractionsApi.d.ts +6 -13
  30. package/lib/InteractionsApi.d.ts.map +1 -1
  31. package/lib/InteractionsApi.js +4 -24
  32. package/lib/InteractionsApi.js.map +1 -1
  33. package/lib/OAuthClientsApi.d.ts +3 -1
  34. package/lib/OAuthClientsApi.d.ts.map +1 -1
  35. package/lib/OAuthClientsApi.js +4 -0
  36. package/lib/OAuthClientsApi.js.map +1 -1
  37. package/lib/OAuthProvidersApi.d.ts +6 -2
  38. package/lib/OAuthProvidersApi.d.ts.map +1 -1
  39. package/lib/OAuthProvidersApi.js +6 -2
  40. package/lib/OAuthProvidersApi.js.map +1 -1
  41. package/lib/RemoteMcpConnectionsApi.d.ts +5 -1
  42. package/lib/RemoteMcpConnectionsApi.d.ts.map +1 -1
  43. package/lib/RemoteMcpConnectionsApi.js +6 -2
  44. package/lib/RemoteMcpConnectionsApi.js.map +1 -1
  45. package/lib/RunsApi.d.ts +3 -2
  46. package/lib/RunsApi.d.ts.map +1 -1
  47. package/lib/RunsApi.js +3 -2
  48. package/lib/RunsApi.js.map +1 -1
  49. package/lib/StreamSource.d.ts +19 -1
  50. package/lib/StreamSource.d.ts.map +1 -1
  51. package/lib/StreamSource.js +31 -1
  52. package/lib/StreamSource.js.map +1 -1
  53. package/lib/UsersApi.d.ts +7 -1
  54. package/lib/UsersApi.d.ts.map +1 -1
  55. package/lib/UsersApi.js +8 -0
  56. package/lib/UsersApi.js.map +1 -1
  57. package/lib/client.d.ts +14 -2
  58. package/lib/client.d.ts.map +1 -1
  59. package/lib/client.js +57 -8
  60. package/lib/client.js.map +1 -1
  61. package/lib/execute.d.ts +16 -2
  62. package/lib/execute.d.ts.map +1 -1
  63. package/lib/execute.js +16 -3
  64. package/lib/execute.js.map +1 -1
  65. package/lib/idempotency-key.d.ts +19 -0
  66. package/lib/idempotency-key.d.ts.map +1 -0
  67. package/lib/idempotency-key.js +34 -0
  68. package/lib/idempotency-key.js.map +1 -0
  69. package/lib/index.d.ts +1 -0
  70. package/lib/index.d.ts.map +1 -1
  71. package/lib/index.js.map +1 -1
  72. package/lib/nodejs/NodeStreamSource.d.ts +11 -1
  73. package/lib/nodejs/NodeStreamSource.d.ts.map +1 -1
  74. package/lib/nodejs/NodeStreamSource.js +56 -16
  75. package/lib/nodejs/NodeStreamSource.js.map +1 -1
  76. package/lib/store/AgentsApi.d.ts +3 -0
  77. package/lib/store/AgentsApi.d.ts.map +1 -1
  78. package/lib/store/AgentsApi.js +10 -1
  79. package/lib/store/AgentsApi.js.map +1 -1
  80. package/lib/store/ContentSourcesApi.d.ts +57 -0
  81. package/lib/store/ContentSourcesApi.d.ts.map +1 -0
  82. package/lib/store/ContentSourcesApi.js +92 -0
  83. package/lib/store/ContentSourcesApi.js.map +1 -0
  84. package/lib/store/CostApi.d.ts +9 -1
  85. package/lib/store/CostApi.d.ts.map +1 -1
  86. package/lib/store/CostApi.js +16 -0
  87. package/lib/store/CostApi.js.map +1 -1
  88. package/lib/store/DashboardApi.d.ts +61 -19
  89. package/lib/store/DashboardApi.d.ts.map +1 -1
  90. package/lib/store/DashboardApi.js +75 -19
  91. package/lib/store/DashboardApi.js.map +1 -1
  92. package/lib/store/DataApi.d.ts +9 -9
  93. package/lib/store/DataApi.d.ts.map +1 -1
  94. package/lib/store/DataApi.js +14 -10
  95. package/lib/store/DataApi.js.map +1 -1
  96. package/lib/store/FilesApi.d.ts +15 -1
  97. package/lib/store/FilesApi.d.ts.map +1 -1
  98. package/lib/store/FilesApi.js +54 -69
  99. package/lib/store/FilesApi.js.map +1 -1
  100. package/lib/store/IndexingApi.d.ts +0 -6
  101. package/lib/store/IndexingApi.d.ts.map +1 -1
  102. package/lib/store/IndexingApi.js +3 -17
  103. package/lib/store/IndexingApi.js.map +1 -1
  104. package/lib/store/NotificationsApi.d.ts +39 -0
  105. package/lib/store/NotificationsApi.d.ts.map +1 -0
  106. package/lib/store/NotificationsApi.js +68 -0
  107. package/lib/store/NotificationsApi.js.map +1 -0
  108. package/lib/store/ObjectsApi.d.ts +6 -7
  109. package/lib/store/ObjectsApi.d.ts.map +1 -1
  110. package/lib/store/ObjectsApi.js +25 -46
  111. package/lib/store/ObjectsApi.js.map +1 -1
  112. package/lib/store/RenderingApi.d.ts.map +1 -1
  113. package/lib/store/RenderingApi.js +1 -0
  114. package/lib/store/RenderingApi.js.map +1 -1
  115. package/lib/store/WorkflowsApi.d.ts +19 -1
  116. package/lib/store/WorkflowsApi.d.ts.map +1 -1
  117. package/lib/store/WorkflowsApi.js +21 -0
  118. package/lib/store/WorkflowsApi.js.map +1 -1
  119. package/lib/store/chunked-upload.d.ts +71 -0
  120. package/lib/store/chunked-upload.d.ts.map +1 -0
  121. package/lib/store/chunked-upload.js +206 -0
  122. package/lib/store/chunked-upload.js.map +1 -0
  123. package/lib/store/client.d.ts +9 -1
  124. package/lib/store/client.d.ts.map +1 -1
  125. package/lib/store/client.js +17 -1
  126. package/lib/store/client.js.map +1 -1
  127. package/lib/store/index.d.ts +3 -0
  128. package/lib/store/index.d.ts.map +1 -1
  129. package/lib/store/index.js +3 -0
  130. package/lib/store/index.js.map +1 -1
  131. package/lib/store/node-request.browser.d.ts +14 -0
  132. package/lib/store/node-request.browser.d.ts.map +1 -0
  133. package/lib/store/node-request.browser.js +20 -0
  134. package/lib/store/node-request.browser.js.map +1 -0
  135. package/lib/store/node-request.d.ts +20 -0
  136. package/lib/store/node-request.d.ts.map +1 -0
  137. package/lib/store/node-request.js +116 -0
  138. package/lib/store/node-request.js.map +1 -0
  139. package/lib/store/node-sessions.browser.d.ts +3 -0
  140. package/lib/store/node-sessions.browser.d.ts.map +1 -0
  141. package/lib/store/node-sessions.browser.js +15 -0
  142. package/lib/store/node-sessions.browser.js.map +1 -0
  143. package/lib/store/node-sessions.d.ts +14 -0
  144. package/lib/store/node-sessions.d.ts.map +1 -0
  145. package/lib/store/node-sessions.js +88 -0
  146. package/lib/store/node-sessions.js.map +1 -0
  147. package/lib/store/signed-url.d.ts +12 -16
  148. package/lib/store/signed-url.d.ts.map +1 -1
  149. package/lib/store/signed-url.js +111 -71
  150. package/lib/store/signed-url.js.map +1 -1
  151. package/lib/store/stream-bytes.d.ts +16 -0
  152. package/lib/store/stream-bytes.d.ts.map +1 -0
  153. package/lib/store/stream-bytes.js +70 -0
  154. package/lib/store/stream-bytes.js.map +1 -0
  155. package/lib/store/stream-termination.d.ts.map +1 -1
  156. package/lib/store/stream-termination.js +17 -16
  157. package/lib/store/stream-termination.js.map +1 -1
  158. package/lib/store/upload-body.d.ts +21 -0
  159. package/lib/store/upload-body.d.ts.map +1 -0
  160. package/lib/store/upload-body.js +32 -0
  161. package/lib/store/upload-body.js.map +1 -0
  162. package/lib/store/upload-content.d.ts +21 -0
  163. package/lib/store/upload-content.d.ts.map +1 -0
  164. package/lib/store/upload-content.js +113 -0
  165. package/lib/store/upload-content.js.map +1 -0
  166. package/lib/store/upload-runtime.d.ts +21 -0
  167. package/lib/store/upload-runtime.d.ts.map +1 -0
  168. package/lib/store/upload-runtime.js +40 -0
  169. package/lib/store/upload-runtime.js.map +1 -0
  170. package/lib/store/zeno-bulk.d.ts +9 -0
  171. package/lib/store/zeno-bulk.d.ts.map +1 -0
  172. package/lib/store/zeno-bulk.js +26 -0
  173. package/lib/store/zeno-bulk.js.map +1 -0
  174. package/lib/user-agent.d.ts +11 -0
  175. package/lib/user-agent.d.ts.map +1 -0
  176. package/lib/user-agent.js +35 -0
  177. package/lib/user-agent.js.map +1 -0
  178. package/lib/vertesia-client.js +10 -9
  179. package/lib/vertesia-client.js.map +1 -1
  180. package/package.json +38 -9
  181. package/src/AccountApi.ts +3 -0
  182. package/src/AccountRolesApi.ts +29 -0
  183. package/src/ApiKeysApi.ts +4 -12
  184. package/src/AppsApi.ts +58 -4
  185. package/src/AuditTrailApi.ts +11 -0
  186. package/src/EnvironmentsApi.ts +2 -2
  187. package/src/IamApi.ts +1 -1
  188. package/src/InteractionCatalogApi.ts +44 -1
  189. package/src/InteractionsApi.ts +11 -33
  190. package/src/OAuthClientsApi.ts +6 -0
  191. package/src/OAuthProvidersApi.ts +7 -2
  192. package/src/RemoteMcpConnectionsApi.ts +7 -3
  193. package/src/RunsApi.ts +7 -2
  194. package/src/StreamSource.ts +29 -0
  195. package/src/UsersApi.ts +10 -1
  196. package/src/client.ts +74 -8
  197. package/src/execute.ts +33 -4
  198. package/src/idempotency-key.ts +34 -0
  199. package/src/index.ts +1 -0
  200. package/src/nodejs/NodeStreamSource.ts +63 -24
  201. package/src/store/AgentsApi.ts +13 -1
  202. package/src/store/ContentSourcesApi.ts +135 -0
  203. package/src/store/CostApi.ts +24 -0
  204. package/src/store/DashboardApi.ts +93 -18
  205. package/src/store/DataApi.ts +14 -10
  206. package/src/store/FilesApi.ts +84 -72
  207. package/src/store/IndexingApi.ts +3 -18
  208. package/src/store/NotificationsApi.ts +103 -0
  209. package/src/store/ObjectsApi.ts +32 -51
  210. package/src/store/RenderingApi.ts +1 -0
  211. package/src/store/WorkflowsApi.ts +25 -0
  212. package/src/store/chunked-upload.ts +272 -0
  213. package/src/store/client.ts +23 -1
  214. package/src/store/index.ts +3 -0
  215. package/src/store/node-request.browser.ts +22 -0
  216. package/src/store/node-request.ts +120 -0
  217. package/src/store/node-sessions.browser.ts +16 -0
  218. package/src/store/node-sessions.ts +109 -0
  219. package/src/store/signed-url.ts +126 -72
  220. package/src/store/stream-bytes.ts +79 -0
  221. package/src/store/stream-termination.ts +24 -24
  222. package/src/store/upload-body.ts +37 -0
  223. package/src/store/upload-content.ts +129 -0
  224. package/src/store/upload-runtime.ts +42 -0
  225. package/src/store/zeno-bulk.ts +30 -0
  226. package/src/user-agent.ts +41 -0
@@ -0,0 +1,22 @@
1
+ /**
2
+ * The browser build of `node-request.ts`, which the `browser` field of `package.json` substitutes for it, so that
3
+ * browser bundles never resolve Node's `http`, `https` and `stream` modules. Uploads only take the Node transport
4
+ * when {@link hasNodeHttp} is true, which it never is here.
5
+ */
6
+ export { ContentLengthMismatchError } from './upload-runtime.js';
7
+
8
+ /**
9
+ * False: this build has no Node transport, even in a runtime that defines `process.versions.node` (an Electron
10
+ * renderer, or a worker with Node compatibility) and was bundled for the browser.
11
+ */
12
+ export function hasNodeHttp(): boolean {
13
+ return false;
14
+ }
15
+
16
+ export function nodeRequest(): never {
17
+ throw new Error('nodeRequest is only available in Node.js');
18
+ }
19
+
20
+ export function exactLength(): never {
21
+ throw new Error('exactLength is only available in Node.js');
22
+ }
@@ -0,0 +1,120 @@
1
+ /**
2
+ * Large signed-URL uploads in Node.js, sent with Node's own `http`/`https` client instead of `fetch`.
3
+ *
4
+ * Node's `fetch` keeps every chunk of a streamed request body in memory until the request completes, so uploading a
5
+ * file through it costs the file's size in memory even when the body is a stream or a file-backed `Blob`. `http`
6
+ * writes the body with backpressure and releases each chunk once it is sent.
7
+ *
8
+ * Node.js only. Browser bundles get `node-request.browser.ts` instead, through the `browser` field of `package.json`,
9
+ * so they never resolve the Node modules this file imports.
10
+ */
11
+ import { ContentLengthMismatchError, contentLengthHeader } from './upload-runtime.js';
12
+
13
+ export { ContentLengthMismatchError, hasNodeHttp } from './upload-runtime.js';
14
+
15
+ type WebReadableStream = Parameters<typeof import('node:stream').Readable.fromWeb>[0];
16
+
17
+ /**
18
+ * A pass-through that fails once more than `length` bytes go through it, or when it ends with fewer. The chunk that
19
+ * completes `length` is held until the source ends, so the server never receives a complete body from a stream
20
+ * that turns out to be longer.
21
+ */
22
+ export function exactLength(length: number, TransformClass: typeof import('node:stream').Transform) {
23
+ let seen = 0;
24
+ let last: Buffer | undefined;
25
+ return new TransformClass({
26
+ transform(chunk: Buffer, _encoding, callback) {
27
+ seen += chunk.byteLength;
28
+ if (seen > length) {
29
+ callback(new ContentLengthMismatchError(length, seen, 'long'));
30
+ } else if (seen === length) {
31
+ last = chunk;
32
+ callback();
33
+ } else {
34
+ callback(null, chunk);
35
+ }
36
+ },
37
+ flush(callback) {
38
+ if (seen < length) {
39
+ callback(new ContentLengthMismatchError(length, seen, 'short'));
40
+ } else {
41
+ callback(null, last);
42
+ }
43
+ },
44
+ });
45
+ }
46
+
47
+ const NULL_BODY_STATUSES = new Set([101, 204, 205, 304]);
48
+
49
+ /** How long the connection may stay idle before the request fails: the headers and body timeouts of undici's fetch. */
50
+ const IDLE_TIMEOUT_MS = 300_000;
51
+
52
+ /**
53
+ * Send a request with a `Blob` or `ReadableStream` body. A `Blob` is sent with its size as `Content-Length`; a
54
+ * stream with the `Content-Length` header it is given, or with chunked transfer encoding when it has none. A body
55
+ * that ends short of its `Content-Length` or runs past it fails the request. Resolves with the response once its
56
+ * headers arrive, like `fetch`; rejects on a connection error, or when the connection is idle for `idleTimeoutMs`.
57
+ */
58
+ export async function nodeRequest(
59
+ url: string,
60
+ init: { method: string; headers?: Record<string, string>; body: Blob | ReadableStream; idleTimeoutMs?: number },
61
+ ): Promise<Response> {
62
+ const [http, https, { Readable, Transform }, { pipeline }] = await Promise.all([
63
+ import('node:http'),
64
+ import('node:https'),
65
+ import('node:stream'),
66
+ import('node:stream/promises'),
67
+ ]);
68
+ const { body } = init;
69
+ const headers: Record<string, string> = { ...init.headers };
70
+ if (body instanceof Blob) {
71
+ for (const name of Object.keys(headers)) {
72
+ if (name.toLowerCase() === 'content-length') delete headers[name];
73
+ }
74
+ headers['content-length'] = String(body.size);
75
+ }
76
+ const target = new URL(url);
77
+ const send = target.protocol === 'http:' ? http.request : https.request;
78
+
79
+ return new Promise<Response>((resolve, reject) => {
80
+ const req = send(target, { method: init.method, headers });
81
+ const idleTimeoutMs = init.idleTimeoutMs ?? IDLE_TIMEOUT_MS;
82
+ req.setTimeout(idleTimeoutMs, () => {
83
+ req.destroy(new Error(`Request to ${target.host} was idle for ${idleTimeoutMs} ms`));
84
+ });
85
+ req.on('response', (res) => {
86
+ const responseHeaders = new Headers();
87
+ for (const [name, value] of Object.entries(res.headers)) {
88
+ if (value === undefined) continue;
89
+ for (const v of Array.isArray(value) ? value : [value]) responseHeaders.append(name, v);
90
+ }
91
+ const status = res.statusCode ?? 0;
92
+ const responseBody = NULL_BODY_STATUSES.has(status)
93
+ ? null
94
+ : (Readable.toWeb(res) as unknown as ReadableStream<Uint8Array>);
95
+ if (!responseBody) res.resume();
96
+ try {
97
+ resolve(
98
+ new Response(responseBody, { status, statusText: res.statusMessage, headers: responseHeaders }),
99
+ );
100
+ } catch (err: unknown) {
101
+ // A status or reason phrase `Response` does not accept: fail the request, not the event loop.
102
+ res.destroy();
103
+ reject(err);
104
+ }
105
+ });
106
+ const source = Readable.fromWeb((body instanceof Blob ? body.stream() : body) as WebReadableStream);
107
+ // An error reading the body ends the request with a "socket hang up"; report the body's error instead.
108
+ let bodyError: unknown;
109
+ source.once('error', (err) => {
110
+ bodyError = err;
111
+ });
112
+ req.on('error', (err) => reject(bodyError ?? err));
113
+ // A stream that does not match its declared length aborts the request instead of sending a truncated or
114
+ // overlong body. (`strictContentLength` reports a short body from `end()` outside the pipeline, as an
115
+ // uncaught exception, so the length is checked here.)
116
+ const length = contentLengthHeader(headers);
117
+ const stages = length === undefined ? [source] : [source, exactLength(length, Transform)];
118
+ pipeline([...stages, req]).catch((err: unknown) => reject(bodyError ?? err));
119
+ });
120
+ }
@@ -0,0 +1,16 @@
1
+ /**
2
+ * The browser build of `node-sessions.ts`, which the `browser` field of `package.json` substitutes for it, so that
3
+ * browser bundles never resolve the storage SDKs. Uploads only open a session when `hasNodeHttp()` is true, which it
4
+ * never is in a browser.
5
+ */
6
+ function nodeOnly(): never {
7
+ throw new Error('Uploading in parts is only available in Node.js');
8
+ }
9
+
10
+ export function uploadGcsResumable(): never {
11
+ return nodeOnly();
12
+ }
13
+
14
+ export function uploadAzureBlocks(): never {
15
+ return nodeOnly();
16
+ }
@@ -0,0 +1,109 @@
1
+ /**
2
+ * The upload-session writers that run on the storage services' own SDKs: Google Cloud Storage resumable uploads and
3
+ * Azure block blobs (see `chunked-upload.ts`). The SDKs are optional peer dependencies, loaded on first use.
4
+ *
5
+ * Node.js only. Browser bundles get `node-sessions.browser.ts` instead, through the `browser` field of
6
+ * `package.json`, so they never resolve the SDKs or Node's `stream` module.
7
+ */
8
+ import type { GcsResumableUploadSession } from '@vertesia/common';
9
+ import type { PartsBody } from './chunked-upload.js';
10
+ import { exactLength } from './node-request.js';
11
+ import { UploadSessionUnavailableError } from './upload-runtime.js';
12
+
13
+ /**
14
+ * The `catch` handler of an optional package's `import()`: a missing package means uploads in parts are unavailable.
15
+ *
16
+ * Each `import()` of an optional package carries webpack's `webpackIgnore` comment and chains this handler directly,
17
+ * the forms webpack and esbuild leave to run time, so a consumer's Node.js bundle builds without the packages.
18
+ */
19
+ function missingPackage(name: string): (err: unknown) => never {
20
+ return (err) => {
21
+ const code = (err as { code?: unknown } | undefined)?.code;
22
+ if (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') {
23
+ throw new UploadSessionUnavailableError(`the optional package ${name}`, err);
24
+ }
25
+ throw err;
26
+ };
27
+ }
28
+
29
+ /** The content as a Node stream that fails, before it ends, when it does not match its declared length. */
30
+ async function nodeReadable(parts: PartsBody): Promise<import('node:stream').Readable> {
31
+ const { Readable, Transform } = await import('node:stream');
32
+ const { pipeline } = await import('node:stream/promises');
33
+ const web = parts.body instanceof Blob ? parts.body.stream() : parts.body;
34
+ const source = Readable.fromWeb(web as Parameters<typeof Readable.fromWeb>[0]);
35
+ if (parts.size === undefined) return source;
36
+ const counted = exactLength(parts.size, Transform);
37
+ // The pipeline forwards an error of the source to `counted`, which is what the SDK reads.
38
+ pipeline(source, counted).catch(() => undefined);
39
+ return counted;
40
+ }
41
+
42
+ /**
43
+ * The SDK's ceiling on retrying, counted from the start of the upload. A session URI expires a week after it is
44
+ * created, so a later retry could not succeed. The retry count is what normally ends the retries, within minutes.
45
+ * See https://cloud.google.com/storage/docs/resumable-uploads
46
+ */
47
+ const GCS_SESSION_LIFETIME_SECONDS = 7 * 24 * 60 * 60;
48
+ /** Retries of failed chunks across the whole upload: the SDK does not reset its count after a chunk succeeds. */
49
+ const GCS_SESSION_MAX_RETRIES = 10;
50
+
51
+ /** Writes the content to a GCS resumable session. Returns the object's MD5 in hex, the ETag a single PUT gives. */
52
+ export async function uploadGcsResumable(
53
+ session: GcsResumableUploadSession,
54
+ parts: PartsBody,
55
+ ): Promise<string | undefined> {
56
+ const [{ IdempotencyStrategy, Storage }, { PassThroughClient }] = await Promise.all([
57
+ import(/* webpackIgnore: true */ '@google-cloud/storage').catch(missingPackage('@google-cloud/storage')),
58
+ import(/* webpackIgnore: true */ 'google-auth-library').catch(missingPackage('google-auth-library')),
59
+ ]);
60
+ const { pipeline } = await import('node:stream/promises');
61
+ const slash = session.path.indexOf('/');
62
+ // The session URI is the only credential the upload needs, so requests carry no other.
63
+ const file = new Storage({
64
+ authClient: new PassThroughClient(),
65
+ retryOptions: {
66
+ // The default strategy retries only uploads with a precondition, which leaves a session with no retries.
67
+ // Resending a chunk is safe: the SDK first asks the session for the offset it persisted.
68
+ idempotencyStrategy: IdempotencyStrategy.RetryAlways,
69
+ // Both limits count from the start of the upload, not per chunk, so the defaults (3 retries within 600
70
+ // seconds) would leave a long upload with none.
71
+ maxRetries: GCS_SESSION_MAX_RETRIES,
72
+ totalTimeout: GCS_SESSION_LIFETIME_SECONDS,
73
+ },
74
+ })
75
+ .bucket(session.path.slice(0, slash))
76
+ .file(session.path.slice(slash + 1));
77
+ const writable = file.createWriteStream({
78
+ uri: session.url,
79
+ resumable: true,
80
+ chunkSize: session.part_size,
81
+ metadata: { contentType: session.mime_type },
82
+ });
83
+ await pipeline(await nodeReadable(parts), writable);
84
+ const md5 = file.metadata?.md5Hash;
85
+ return typeof md5 === 'string' ? Buffer.from(md5, 'base64').toString('hex') : undefined;
86
+ }
87
+
88
+ /** Uploads the content as blocks of `blockSize` bytes, one at a time, then commits them. Returns the blob's ETag. */
89
+ export async function uploadAzureBlocks(
90
+ url: string,
91
+ blockSize: number,
92
+ contentType: string | undefined,
93
+ parts: PartsBody,
94
+ ): Promise<string | undefined> {
95
+ const { BlockBlobClient } = await import(/* webpackIgnore: true */ '@azure/storage-blob').catch(
96
+ missingPackage('@azure/storage-blob'),
97
+ );
98
+ const readable = await nodeReadable(parts);
99
+ try {
100
+ const response = await new BlockBlobClient(url).uploadStream(readable, blockSize, 1, {
101
+ blobHTTPHeaders: { blobContentType: contentType },
102
+ });
103
+ return response.etag;
104
+ } catch (err: unknown) {
105
+ // The SDK stops reading but leaves the stream open; destroying it cancels the source.
106
+ readable.destroy();
107
+ throw err;
108
+ }
109
+ }
@@ -9,10 +9,24 @@
9
9
  * restores retry behaviour for those storage hops.
10
10
  *
11
11
  * Note on streamed bodies: a `ReadableStream` body cannot be replayed once it has
12
- * been consumed, so it is buffered into memory before the first attempt to make
13
- * retries safe. Callers transferring very large streams should be aware of this
14
- * memory cost.
12
+ * been consumed. Up to {@link MAX_BUFFERED_STREAM_BYTES} of it is buffered so that
13
+ * small bodies keep their retries. In Node.js, a longer stream is never held whole in
14
+ * memory: where the storage service accepts a body of unknown length it is sent once,
15
+ * as a stream, without retries (see {@link acceptsStreamedUpload}). Send a `Blob` backed
16
+ * by a local file (Node's `fs.openAsBlob`) to keep retries for large files without a
17
+ * copy in memory. A browser buffers a stream whole, as most browsers cannot send one.
18
+ *
19
+ * A stream whose length the caller declares in a `Content-Length` header is, in Node.js,
20
+ * streamed with that length to any service, and fails if it ends short of it or runs
21
+ * past it.
22
+ *
23
+ * In Node.js, a body over that size, or a streamed one, is sent with Node's `http`
24
+ * client rather than `fetch`, which holds a streamed request body in memory until the
25
+ * request completes (see {@link nodeRequest}).
15
26
  */
27
+ import { hasNodeHttp, nodeRequest } from './node-request.js';
28
+ import { chunkToBlobPart, continueStream } from './stream-bytes.js';
29
+ import { ContentLengthMismatchError, contentLengthHeader } from './upload-runtime.js';
16
30
 
17
31
  /** HTTP statuses that storage backends return for transient, retryable conditions. */
18
32
  const DEFAULT_RETRYABLE_STATUSES: ReadonlySet<number> = new Set([429, 500, 502, 503, 504]);
@@ -22,6 +36,9 @@ const DEFAULT_BASE_DELAY_MS = 500;
22
36
  const DEFAULT_MAX_DELAY_MS = 8_000;
23
37
  const MAX_RETRY_AFTER_MS = 60_000;
24
38
 
39
+ /** The most of a stream body that is buffered to allow retries: 16 MiB. */
40
+ export const MAX_BUFFERED_STREAM_BYTES = 16 * 1024 * 1024;
41
+
25
42
  export interface SignedUrlFetchOptions {
26
43
  method?: string;
27
44
  headers?: Record<string, string>;
@@ -36,12 +53,17 @@ export interface SignedUrlFetchOptions {
36
53
  retryableStatuses?: ReadonlySet<number>;
37
54
  }
38
55
 
39
- const AZURE_BLOB_HOST_SUFFIX = '.blob.core.windows.net';
56
+ /** Blob Storage host suffixes of the public Azure cloud and Azure Government. */
57
+ const AZURE_BLOB_HOST_SUFFIXES = ['.blob.core.windows.net', '.blob.core.usgovcloudapi.net'];
40
58
 
41
- /** Whether a signed URL points at Azure Blob Storage (a SAS URL on `<account>.blob.core.windows.net`). */
59
+ /**
60
+ * Whether a signed URL points at Azure Blob Storage: a SAS URL on `<account>.blob.core.windows.net`, or
61
+ * `<account>.blob.core.usgovcloudapi.net` in Azure Government.
62
+ */
42
63
  export function isAzureBlobUrl(url: string): boolean {
43
64
  try {
44
- return new URL(url).hostname.toLowerCase().endsWith(AZURE_BLOB_HOST_SUFFIX);
65
+ const hostname = new URL(url).hostname.toLowerCase();
66
+ return AZURE_BLOB_HOST_SUFFIXES.some((suffix) => hostname.endsWith(suffix));
45
67
  } catch {
46
68
  return false;
47
69
  }
@@ -63,6 +85,29 @@ export function signedUrlUploadHeaders(
63
85
  return { ...headers, 'x-ms-blob-type': 'BlockBlob' };
64
86
  }
65
87
 
88
+ /**
89
+ * Whether a signed URL's storage service accepts an upload of unknown length, sent with chunked transfer encoding
90
+ * and no `Content-Length`. Google Cloud Storage does; Amazon S3 (`MissingContentLength`) and Azure Blob Storage
91
+ * (411 Length Required) need the length up front.
92
+ */
93
+ export function acceptsStreamedUpload(url: string): boolean {
94
+ try {
95
+ const hostname = new URL(url).hostname.toLowerCase();
96
+ return hostname === 'storage.googleapis.com' || hostname.endsWith('.storage.googleapis.com');
97
+ } catch {
98
+ return false;
99
+ }
100
+ }
101
+
102
+ function isStream(body: BodyInit | null | undefined): boolean {
103
+ return typeof ReadableStream !== 'undefined' && body instanceof ReadableStream;
104
+ }
105
+
106
+ function withoutContentLength(headers: Record<string, string> | undefined): Record<string, string> | undefined {
107
+ if (!headers) return headers;
108
+ return Object.fromEntries(Object.entries(headers).filter(([name]) => name.toLowerCase() !== 'content-length'));
109
+ }
110
+
66
111
  function sleep(ms: number): Promise<void> {
67
112
  return new Promise((resolve) => setTimeout(resolve, ms));
68
113
  }
@@ -93,77 +138,61 @@ function backoffMs(attempt: number, baseDelayMs: number, maxDelayMs: number, res
93
138
  return Math.floor(Math.random() * capped);
94
139
  }
95
140
 
96
- const textEncoder = new TextEncoder();
97
-
98
- /**
99
- * Normalize one `ReadableStream` chunk to a byte-backed `BlobPart`.
100
- *
101
- * A web stream produced from a Node `Readable.from(<string>)` (e.g. via
102
- * `Readable.toWeb`, which `NodeStreamSource` uses) yields *string* chunks. Buffering
103
- * such a stream with `new Response(stream).blob()` throws under undici with
104
- * "TypeError: Received non-Uint8Array chunk", which breaks every signed-URL upload of
105
- * a text/JSON body (extracted text previews, agent artifacts, tool storage). Encoding
106
- * chunks ourselves keeps both string and binary bodies uploadable.
107
- */
108
- function chunkToBlobPart(chunk: unknown): BlobPart {
109
- if (typeof chunk === 'string') {
110
- return textEncoder.encode(chunk);
111
- }
112
- if (chunk instanceof Blob) {
113
- return chunk;
114
- }
115
- if (chunk instanceof ArrayBuffer) {
116
- return new Uint8Array(chunk);
117
- }
118
- // Covers Uint8Array and every other typed-array / DataView view.
119
- if (ArrayBuffer.isView(chunk)) {
120
- return new Uint8Array(chunk.buffer as ArrayBuffer, chunk.byteOffset, chunk.byteLength);
121
- }
122
- // Fail loud rather than uploading e.g. "[object Object]" from an accidental
123
- // object-mode stream — silently corrupting the stored content is worse than a clear error.
124
- throw new TypeError(
125
- `Unsupported signed-URL upload chunk of type "${typeof chunk}"; ` +
126
- `body streams must yield string or binary (Uint8Array/ArrayBuffer/DataView/Blob) chunks.`,
127
- );
141
+ /** A request body, and whether it can be sent again for a retry. */
142
+ interface PreparedBody {
143
+ body: BodyInit | undefined;
144
+ replayable: boolean;
128
145
  }
129
146
 
130
147
  /**
131
- * Buffer a `ReadableStream` body into a `Blob` so the request can be safely
132
- * replayed across retries. Other body types (`Blob`/`File`, `ArrayBuffer`,
133
- * typed arrays, strings, `URLSearchParams`) are already replayable and pass
134
- * through unchanged.
148
+ * Make a body safe to send. Bodies other than a `ReadableStream` (`Blob`/`File`, `ArrayBuffer`, typed arrays,
149
+ * strings, `URLSearchParams`) are already replayable and pass through unchanged.
150
+ *
151
+ * A stream is read until it ends or passes `maxBufferedBytes`. A stream that ends first is returned as a `Blob`, so
152
+ * it can be retried. A longer one is returned as a stream that yields the bytes read so far and then the rest,
153
+ * unless `bufferWhole` is set, in which case the rest is buffered too.
135
154
  *
136
- * The stream is drained manually (rather than `new Response(stream).blob()`) so that
137
- * string chunks are encoded to bytes — see {@link chunkToBlobPart}.
155
+ * Chunks are normalized one by one (rather than `new Response(stream).blob()`) so that string chunks are encoded to
156
+ * bytes — see {@link chunkToBlobPart}.
138
157
  */
139
- async function toReplayableBody(body: BodyInit | null | undefined): Promise<BodyInit | undefined> {
158
+ async function prepareBody(
159
+ body: BodyInit | null | undefined,
160
+ maxBufferedBytes: number,
161
+ bufferWhole: boolean,
162
+ ): Promise<PreparedBody> {
140
163
  if (body == null) {
141
- return undefined;
164
+ return { body: undefined, replayable: true };
142
165
  }
143
- if (typeof ReadableStream !== 'undefined' && body instanceof ReadableStream) {
144
- const reader = (body as ReadableStream<unknown>).getReader();
145
- const parts: BlobPart[] = [];
146
- try {
147
- for (;;) {
148
- const { done, value } = await reader.read();
149
- if (done) {
150
- break;
151
- }
152
- // Normalize every chunk (a stray null/undefined is rejected by
153
- // chunkToBlobPart) so a malformed stream fails loudly instead of
154
- // silently uploading a truncated body.
155
- parts.push(chunkToBlobPart(value));
166
+ if (typeof ReadableStream === 'undefined' || !(body instanceof ReadableStream)) {
167
+ return { body, replayable: true };
168
+ }
169
+ const reader = (body as ReadableStream<unknown>).getReader();
170
+ const parts: BlobPart[] = [];
171
+ let buffered = 0;
172
+ try {
173
+ for (;;) {
174
+ if (!bufferWhole && buffered > maxBufferedBytes) {
175
+ return { body: continueStream(parts, reader), replayable: false };
156
176
  }
157
- } catch (err) {
158
- // Signal the producer to stop and release its resources before propagating.
159
- await reader.cancel(err).catch(() => undefined);
160
- throw err;
161
- } finally {
162
- reader.releaseLock();
177
+ const { done, value } = await reader.read();
178
+ if (done) {
179
+ break;
180
+ }
181
+ // Normalize every chunk (a stray null/undefined is rejected by
182
+ // chunkToBlobPart) so a malformed stream fails loudly instead of
183
+ // silently uploading a truncated body.
184
+ const part = chunkToBlobPart(value);
185
+ parts.push(part);
186
+ buffered += part instanceof Blob ? part.size : (part as Uint8Array).byteLength;
163
187
  }
164
- return new Blob(parts);
188
+ } catch (err) {
189
+ // Signal the producer to stop and release its resources before propagating.
190
+ await reader.cancel(err).catch(() => undefined);
191
+ reader.releaseLock();
192
+ throw err;
165
193
  }
166
- return body;
194
+ reader.releaseLock();
195
+ return { body: new Blob(parts), replayable: true };
167
196
  }
168
197
 
169
198
  /**
@@ -189,14 +218,39 @@ export async function fetchSignedUrl(url: string, options: SignedUrlFetchOptions
189
218
  retryableStatuses = DEFAULT_RETRYABLE_STATUSES,
190
219
  } = options;
191
220
 
192
- const body = await toReplayableBody(options.body);
193
- const requestHeaders = method.toUpperCase() === 'PUT' ? signedUrlUploadHeaders(url, headers) : headers;
221
+ // In Node.js, a stream longer than the buffer is sent once as a stream where that works: to a service that
222
+ // accepts a body of unknown length, or with the length the caller declared. Elsewhere it is still buffered
223
+ // whole: S3 and Azure reject a body without a length, and browsers can neither set one nor, in most of them,
224
+ // send a stream at all.
225
+ const declaredLength = isStream(options.body) ? contentLengthHeader(headers) : undefined;
226
+ const streamable = hasNodeHttp() && (acceptsStreamedUpload(url) || declaredLength !== undefined);
227
+ const { body, replayable } = await prepareBody(options.body, MAX_BUFFERED_STREAM_BYTES, !streamable);
228
+ let sendHeaders = headers;
229
+ if (declaredLength !== undefined && body instanceof Blob) {
230
+ if (body.size !== declaredLength) {
231
+ throw new ContentLengthMismatchError(
232
+ declaredLength,
233
+ body.size,
234
+ body.size < declaredLength ? 'short' : 'long',
235
+ );
236
+ }
237
+ // the buffered body sets its own length
238
+ sendHeaders = withoutContentLength(headers);
239
+ }
240
+ const requestHeaders = method.toUpperCase() === 'PUT' ? signedUrlUploadHeaders(url, sendHeaders) : sendHeaders;
241
+ const maxAttempts = replayable ? attempts : 1;
242
+ // Only Node.js streams a body (`streamable`), and always with Node's http client, so fetch only gets buffered ones.
243
+ const large = !replayable || (body instanceof Blob && body.size > MAX_BUFFERED_STREAM_BYTES);
244
+ const send =
245
+ large && hasNodeHttp()
246
+ ? () => nodeRequest(url, { method, headers: requestHeaders, body: body as Blob | ReadableStream })
247
+ : () => fetch(url, { method, headers: requestHeaders, body });
194
248
 
195
249
  let lastError: unknown;
196
- for (let attempt = 0; attempt < attempts; attempt++) {
197
- const isLastAttempt = attempt === attempts - 1;
250
+ for (let attempt = 0; attempt < maxAttempts; attempt++) {
251
+ const isLastAttempt = attempt === maxAttempts - 1;
198
252
  try {
199
- const res = await fetch(url, { method, headers: requestHeaders, body });
253
+ const res = await send();
200
254
  if (res.ok || !retryableStatuses.has(res.status) || isLastAttempt) {
201
255
  return res;
202
256
  }
@@ -0,0 +1,79 @@
1
+ /** Byte handling for upload bodies read from a `ReadableStream`. Internal: not exported from the package. */
2
+
3
+ const textEncoder = new TextEncoder();
4
+
5
+ /**
6
+ * Normalize one `ReadableStream` chunk to a byte-backed `BlobPart`.
7
+ *
8
+ * A web stream produced from a Node `Readable.from(<string>)` (e.g. via
9
+ * `Readable.toWeb`, which `NodeStreamSource` uses) yields *string* chunks. Buffering
10
+ * such a stream with `new Response(stream).blob()` throws under undici with
11
+ * "TypeError: Received non-Uint8Array chunk", which breaks every signed-URL upload of
12
+ * a text/JSON body (extracted text previews, agent artifacts, tool storage). Encoding
13
+ * chunks ourselves keeps both string and binary bodies uploadable.
14
+ */
15
+ export function chunkToBlobPart(chunk: unknown): BlobPart {
16
+ if (typeof chunk === 'string') {
17
+ return textEncoder.encode(chunk);
18
+ }
19
+ if (chunk instanceof Blob) {
20
+ return chunk;
21
+ }
22
+ if (chunk instanceof ArrayBuffer) {
23
+ return new Uint8Array(chunk);
24
+ }
25
+ // Covers Uint8Array and every other typed-array / DataView view.
26
+ if (ArrayBuffer.isView(chunk)) {
27
+ return new Uint8Array(chunk.buffer as ArrayBuffer, chunk.byteOffset, chunk.byteLength);
28
+ }
29
+ // Fail loud rather than uploading e.g. "[object Object]" from an accidental
30
+ // object-mode stream — silently corrupting the stored content is worse than a clear error.
31
+ throw new TypeError(
32
+ `Unsupported signed-URL upload chunk of type "${typeof chunk}"; ` +
33
+ `body streams must yield string or binary (Uint8Array/ArrayBuffer/DataView/Blob) chunks.`,
34
+ );
35
+ }
36
+
37
+ /** A byte stream of `head`, the parts already read, then what is left in `reader`. */
38
+ export function continueStream(
39
+ head: BlobPart[],
40
+ reader: ReadableStreamDefaultReader<unknown>,
41
+ ): ReadableStream<Uint8Array> {
42
+ const pending = [...head];
43
+ return new ReadableStream<Uint8Array>(
44
+ {
45
+ async pull(controller) {
46
+ const next = pending.shift();
47
+ if (next !== undefined) {
48
+ controller.enqueue(await partToBytes(next));
49
+ return;
50
+ }
51
+ try {
52
+ const { done, value } = await reader.read();
53
+ if (done) {
54
+ reader.releaseLock();
55
+ controller.close();
56
+ } else {
57
+ controller.enqueue(await partToBytes(chunkToBlobPart(value)));
58
+ }
59
+ } catch (err) {
60
+ // An error in pull errors this stream without calling cancel, so the source is cancelled here.
61
+ pending.length = 0;
62
+ await reader.cancel(err).catch(() => undefined);
63
+ reader.releaseLock();
64
+ throw err;
65
+ }
66
+ },
67
+ async cancel(reason) {
68
+ pending.length = 0;
69
+ await reader.cancel(reason);
70
+ reader.releaseLock();
71
+ },
72
+ },
73
+ { highWaterMark: 0 },
74
+ );
75
+ }
76
+
77
+ export async function partToBytes(part: BlobPart): Promise<Uint8Array> {
78
+ return part instanceof Blob ? new Uint8Array(await part.arrayBuffer()) : (part as Uint8Array);
79
+ }
@@ -15,32 +15,32 @@ function isRootProcessMessage(details: MessageDetails, rootRunId: string): boole
15
15
  return !processRunId || processRunId === rootRunId;
16
16
  }
17
17
 
18
- export function shouldCloseAgentRunStream(message: AgentMessage, rootRunId: string, closeOnIdle = false): boolean {
19
- if (message.type === AgentMessageType.TERMINATED) {
20
- return isRootProcessMessage(message.details, rootRunId);
21
- }
22
-
23
- if (
24
- (message.type === AgentMessageType.COMPLETE || (closeOnIdle && message.type === AgentMessageType.IDLE)) &&
25
- (message.workstream_id ?? 'main') === 'main'
26
- ) {
27
- return isRootProcessMessage(message.details, rootRunId);
28
- }
18
+ /**
19
+ * Only the main workstream's COMPLETE or TERMINATED ends the run (and IDLE when `closeOnIdle` is set).
20
+ * Sub-agents publish their own COMPLETE and TERMINATED on the parent's channel under their own
21
+ * workstream id, and child process runs publish theirs with a different `process_run_id`; neither
22
+ * ends the root run.
23
+ */
24
+ function isRunEndType(type: AgentMessageType, closeOnIdle: boolean): boolean {
25
+ return (
26
+ type === AgentMessageType.COMPLETE ||
27
+ type === AgentMessageType.TERMINATED ||
28
+ (closeOnIdle && type === AgentMessageType.IDLE)
29
+ );
30
+ }
29
31
 
30
- return false;
32
+ export function shouldCloseAgentRunStream(message: AgentMessage, rootRunId: string, closeOnIdle = false): boolean {
33
+ return (
34
+ isRunEndType(message.type, closeOnIdle) &&
35
+ (message.workstream_id ?? 'main') === 'main' &&
36
+ isRootProcessMessage(message.details, rootRunId)
37
+ );
31
38
  }
32
39
 
33
40
  export function shouldCloseCompactRunStream(message: CompactMessage, rootRunId: string, closeOnIdle = false): boolean {
34
- if (message.t === AgentMessageType.TERMINATED) {
35
- return isRootProcessMessage(message.d, rootRunId);
36
- }
37
-
38
- if (
39
- (message.t === AgentMessageType.COMPLETE || (closeOnIdle && message.t === AgentMessageType.IDLE)) &&
40
- (message.w ?? 'main') === 'main'
41
- ) {
42
- return isRootProcessMessage(message.d, rootRunId);
43
- }
44
-
45
- return false;
41
+ return (
42
+ isRunEndType(message.t, closeOnIdle) &&
43
+ (message.w ?? 'main') === 'main' &&
44
+ isRootProcessMessage(message.d, rootRunId)
45
+ );
46
46
  }