The best way to control Claude Code, Codex and more from any computer or phone

main
ts 658 lines 20.7 KB
Raw
1 // Alchemy modifications are licensed under Apache-2.0.
2 // This file includes third-party code; see /THIRD_PARTY_LICENSES.md.
3 import {
4 InvalidStepReadableStreamError,
5 OversizedStreamChunkError,
6 StreamOutputStorageLimitError,
7 UnsupportedStreamChunkError,
8 WorkflowTimeoutError,
9 } from "./errors.ts";
10
11 // ── Constants ───────────────────────────────────────────────────────────────
12
13 export const DEFAULT_STREAM_OUTPUT_CHUNK_SIZE = 256 * 1024;
14 export const STREAM_OUTPUT_META_SUFFIX = "-value-stream-meta";
15 export const MAX_STREAM_OUTPUT_INPUT_CHUNK_BYTES = 16 * 1024 * 1024;
16 export const STREAMING_STEP_CHUNKS_TABLE = "streaming_step_chunks";
17 export const MAX_OUTPUT_SHOWN_IN_LOGS = 1024;
18
19 const DO_STORAGE_LIMIT = 1024 * 1024 * 1024 + 100 * 1024 * 1024;
20 const STREAM_OUTPUT_STORAGE_WRITE_HEADROOM_BYTES = 16 * 1024;
21
22 // ── Types ───────────────────────────────────────────────────────────────────
23
24 export enum StreamOutputState {
25 Pending = "pending",
26 Committing = "committing",
27 Complete = "complete",
28 }
29
30 export type StreamOutputMeta = {
31 version: 1;
32 state: StreamOutputState;
33 attempt: number;
34 startedAt: number;
35 chunkCount: number;
36 totalBytes: number;
37 committedAt: number | null;
38 };
39
40 export type StoredStreamOutputPreview = { type: "text"; output: string } | { type: "binary" };
41
42 // oxlint-disable-next-line effecttsgo/extends-native-error -- vendored workers-sdk Workflows code; the error `name` is part of the protocol surfaced to user code across RPC
43 export class InvalidStoredStreamOutputError extends Error {
44 name = "InvalidStoredStreamOutputError";
45 }
46
47 // ── Helpers ─────────────────────────────────────────────────────────────────
48
49 export function getStreamOutputMetaKey(cacheKey: string): string {
50 return `${cacheKey}${STREAM_OUTPUT_META_SUFFIX}`;
51 }
52
53 export function isReadableStreamLike(value: unknown): value is ReadableStream<unknown> {
54 return value instanceof ReadableStream;
55 }
56
57 function createInvalidStepReadableStreamError(): InvalidStepReadableStreamError {
58 return new InvalidStepReadableStreamError(
59 "Step returned a ReadableStream that is already locked or otherwise unreadable. Return a fresh, unlocked ReadableStream from step.do().",
60 );
61 }
62
63 function createOversizedStreamChunkError(): OversizedStreamChunkError {
64 return new OversizedStreamChunkError(
65 `Step returned a ReadableStream chunk larger than the maximum allowed size of ${MAX_STREAM_OUTPUT_INPUT_CHUNK_BYTES} bytes. ` +
66 "Return smaller chunks from step.do().",
67 );
68 }
69
70 /**
71 * Normalize any incoming chunk to Uint8Array.
72 * Accepts ArrayBuffer, TypedArrays (except DataView), and Uint8Array directly.
73 * Rejects strings, objects, and other non-binary types.
74 */
75 function normalizeChunkToUint8Array(value: unknown): Uint8Array {
76 if (value instanceof Uint8Array) {
77 return value;
78 }
79
80 if (value instanceof ArrayBuffer) {
81 return new Uint8Array(value);
82 }
83
84 if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
85 return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
86 }
87
88 throw new UnsupportedStreamChunkError(
89 "Step returned a ReadableStream with unsupported chunk type. " +
90 "Only ArrayBuffer and TypedArray chunks are supported.",
91 );
92 }
93
94 // ── Buffer helpers ──────────────────────────────────────────────────────────
95
96 function takeBufferedBytes(bufferedChunks: Array<Uint8Array>, byteLength: number): Uint8Array {
97 const output = new Uint8Array(byteLength);
98 let offset = 0;
99
100 while (offset < byteLength) {
101 const chunk = bufferedChunks[0];
102 const remaining = byteLength - offset;
103
104 if (chunk.byteLength <= remaining) {
105 output.set(chunk, offset);
106 offset += chunk.byteLength;
107 bufferedChunks.shift();
108 continue;
109 }
110
111 output.set(chunk.subarray(0, remaining), offset);
112 bufferedChunks[0] = chunk.subarray(remaining);
113 offset += remaining;
114 }
115
116 return output;
117 }
118
119 // ── Stream iteration ────────────────────────────────────────────────────────
120
121 async function* iterateStreamChunks(
122 stream: ReadableStream<unknown>,
123 signal?: AbortSignal,
124 ): AsyncGenerator<Uint8Array> {
125 if (stream.locked) {
126 throw createInvalidStepReadableStreamError();
127 }
128
129 if (signal?.aborted) {
130 throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
131 }
132
133 let reader: ReadableStreamDefaultReader<unknown>;
134 try {
135 reader = stream.getReader();
136 } catch (error) {
137 if (error instanceof TypeError) {
138 throw createInvalidStepReadableStreamError();
139 }
140 throw error;
141 }
142
143 const onAbort = () => {
144 void reader
145 .cancel(signal?.reason ?? new DOMException("The operation was aborted.", "AbortError"))
146 .catch(() => {});
147 };
148
149 signal?.addEventListener("abort", onAbort, { once: true });
150 let fullyRead = false;
151
152 try {
153 while (true) {
154 let readResult: ReadableStreamReadResult<unknown>;
155 try {
156 readResult = await reader.read();
157 } catch (readError) {
158 // When the abort signal has already fired, the read error is an
159 // expected cancellation (e.g. step timeout or engine shutdown).
160 // Re-throw the original abort reason so callers can distinguish
161 // timeouts from genuine stream failures.
162 if (signal?.aborted) {
163 throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
164 }
165
166 // Any other read failure (broken pipe, upstream connection
167 // drop, encoding mismatch, etc.) means the ReadableStream the
168 // step returned is unusable.
169 throw new InvalidStepReadableStreamError(
170 "Failed to read from step ReadableStream output. " +
171 (readError instanceof Error ? readError.message : String(readError)),
172 );
173 }
174
175 if (signal?.aborted) {
176 throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
177 }
178 if (readResult.done) {
179 fullyRead = true;
180 return;
181 }
182
183 yield normalizeChunkToUint8Array(readResult.value);
184 }
185 } finally {
186 signal?.removeEventListener("abort", onAbort);
187 if (!fullyRead) {
188 await reader
189 .cancel(new Error("stream output consumption stopped before completion"))
190 .catch(() => {});
191 }
192 try {
193 reader.releaseLock();
194 } catch {
195 // Reader may still be processing cancel()
196 }
197 }
198 }
199
200 // ── SQL helpers ─────────────────────────────────────────────────────────────
201
202 function deleteAttemptChunks(
203 storage: DurableObjectStorage,
204 cacheKey: string,
205 attempt: number,
206 ): void {
207 // eslint-disable-next-line workers-sdk/no-unsafe-command-execution -- DO SQL exec, not child_process
208 storage.sql.exec(
209 `DELETE FROM ${STREAMING_STEP_CHUNKS_TABLE} WHERE cache_key = ? AND attempt = ?`,
210 cacheKey,
211 attempt,
212 );
213 }
214
215 async function deleteMetaForAttempt(
216 storage: DurableObjectStorage,
217 cacheKey: string,
218 attempt: number,
219 ): Promise<void> {
220 const metaKey = getStreamOutputMetaKey(cacheKey);
221 const maybeMeta = await storage.get<StreamOutputMeta>(metaKey);
222 if (maybeMeta === undefined) {
223 return;
224 }
225 if (maybeMeta.attempt !== attempt) {
226 return;
227 }
228 await storage.delete(metaKey);
229 }
230
231 // ── Integrity validation ────────────────────────────────────────────────────
232
233 type StreamOutputChunkSummary = {
234 chunkCount: number;
235 minChunkIndex: number | null;
236 maxChunkIndex: number | null;
237 totalBytes: number;
238 };
239
240 function getStreamOutputChunkSummary(
241 storage: DurableObjectStorage,
242 cacheKey: string,
243 attempt: number,
244 ): StreamOutputChunkSummary {
245 const row = storage.sql
246 .exec<StreamOutputChunkSummary>(
247 [
248 `SELECT`,
249 ` COUNT(*) AS chunkCount,`,
250 ` MIN(chunk_index) AS minChunkIndex,`,
251 ` MAX(chunk_index) AS maxChunkIndex,`,
252 ` CAST(COALESCE(SUM(LENGTH(chunk)), 0) AS INTEGER) AS totalBytes`,
253 `FROM ${STREAMING_STEP_CHUNKS_TABLE}`,
254 `WHERE cache_key = ? AND attempt = ?`,
255 ].join("\n"),
256 cacheKey,
257 attempt,
258 )
259 .one();
260
261 if (row === null) {
262 throw new Error("Expected stream chunk summary query to return a row");
263 }
264 return row;
265 }
266
267 export function getInvalidStoredStreamOutputError(
268 storage: DurableObjectStorage,
269 cacheKey: string,
270 meta: StreamOutputMeta,
271 ): InvalidStoredStreamOutputError | undefined {
272 const summary = getStreamOutputChunkSummary(storage, cacheKey, meta.attempt);
273
274 if (meta.chunkCount === 0) {
275 if (
276 summary.chunkCount === 0 &&
277 summary.totalBytes === 0 &&
278 summary.minChunkIndex === null &&
279 summary.maxChunkIndex === null
280 ) {
281 return undefined;
282 }
283 } else if (
284 summary.chunkCount === meta.chunkCount &&
285 summary.minChunkIndex === 0 &&
286 summary.maxChunkIndex === meta.chunkCount - 1 &&
287 summary.totalBytes === meta.totalBytes
288 ) {
289 return undefined;
290 }
291
292 return new InvalidStoredStreamOutputError(
293 `Stored streamed step output is corrupt or incomplete for cache key ${cacheKey}. ` +
294 `Expected ${meta.chunkCount} chunks / ${meta.totalBytes} bytes, found ` +
295 `${summary.chunkCount} chunks / ${summary.totalBytes} bytes with chunk index range ` +
296 `${summary.minChunkIndex ?? "null"}..${summary.maxChunkIndex ?? "null"}.`,
297 );
298 }
299
300 // ── Preview ─────────────────────────────────────────────────────────────────
301
302 function readStreamOutputPreviewBytes(options: {
303 storage: DurableObjectStorage;
304 cacheKey: string;
305 attempt: number;
306 maxBytes: number;
307 }): Uint8Array {
308 const { storage, cacheKey, attempt, maxBytes } = options;
309 // eslint-disable-next-line workers-sdk/no-unsafe-command-execution -- DO SQL exec, not child_process
310 const cursor = storage.sql.exec<{
311 chunk_index: number;
312 chunk: ArrayBuffer;
313 }>(
314 `SELECT chunk_index, chunk FROM ${STREAMING_STEP_CHUNKS_TABLE} WHERE cache_key = ? AND attempt = ? ORDER BY chunk_index`,
315 cacheKey,
316 attempt,
317 );
318 const previewChunks: Array<Uint8Array> = [];
319 let expectedChunkIndex = 0;
320 let totalBytes = 0;
321
322 while (totalBytes < maxBytes) {
323 const row = cursor.next();
324 if (row.done) {
325 break;
326 }
327
328 if (row.value.chunk_index !== expectedChunkIndex) {
329 throw new InvalidStoredStreamOutputError(
330 `Missing chunk ${expectedChunkIndex} for streamed step output`,
331 );
332 }
333
334 if (!(row.value.chunk instanceof ArrayBuffer)) {
335 throw new InvalidStoredStreamOutputError(
336 "Invalid chunk type returned from streaming_step_chunks table",
337 );
338 }
339
340 const chunkBytes = new Uint8Array(row.value.chunk);
341 const remainingBytes = maxBytes - totalBytes;
342 const previewChunk =
343 chunkBytes.byteLength > remainingBytes ? chunkBytes.subarray(0, remainingBytes) : chunkBytes;
344
345 previewChunks.push(previewChunk);
346 totalBytes += previewChunk.byteLength;
347 expectedChunkIndex++;
348 }
349
350 return takeBufferedBytes(previewChunks, totalBytes);
351 }
352
353 export function getStoredStreamOutputPreview(options: {
354 storage: DurableObjectStorage;
355 cacheKey: string;
356 meta: StreamOutputMeta;
357 maxChars: number;
358 }): StoredStreamOutputPreview {
359 const { storage, cacheKey, meta, maxChars } = options;
360 if (meta.state !== StreamOutputState.Complete) {
361 throw new Error("Cannot preview streamed step output before it is complete");
362 }
363
364 // UTF-8 uses at most 4 bytes per code point
365 const maxPreviewBytes = maxChars * 4;
366 const previewBytes = readStreamOutputPreviewBytes({
367 storage,
368 cacheKey,
369 attempt: meta.attempt,
370 maxBytes: maxPreviewBytes,
371 });
372 const previewTruncatedByBytes = meta.totalBytes > previewBytes.byteLength;
373
374 try {
375 const decoded = new TextDecoder("utf-8", {
376 fatal: true,
377 ignoreBOM: false,
378 }).decode(previewBytes, { stream: previewTruncatedByBytes });
379
380 const previewOutput = decoded.substring(0, maxChars);
381 if (decoded.length > maxChars || previewTruncatedByBytes) {
382 return { type: "text", output: previewOutput + "[truncated output]" };
383 }
384 return { type: "text", output: previewOutput };
385 } catch {
386 return { type: "binary" };
387 }
388 }
389
390 // ── Cleanup ─────────────────────────────────────────────────────────────────
391
392 export async function cleanupPendingStreamOutput(
393 storage: DurableObjectStorage,
394 cacheKey: string,
395 ): Promise<void> {
396 const metaKey = getStreamOutputMetaKey(cacheKey);
397 const maybeMeta = await storage.get<StreamOutputMeta>(metaKey);
398
399 if (maybeMeta === undefined) {
400 return;
401 }
402
403 if (maybeMeta.state === StreamOutputState.Complete) {
404 return;
405 }
406
407 await rollbackStreamOutput(storage, cacheKey, maybeMeta.attempt);
408 }
409
410 export async function rollbackStreamOutput(
411 storage: DurableObjectStorage,
412 cacheKey: string,
413 attempt: number,
414 ): Promise<void> {
415 deleteAttemptChunks(storage, cacheKey, attempt);
416 await deleteMetaForAttempt(storage, cacheKey, attempt);
417 }
418
419 // ── Write ───────────────────────────────────────────────────────────────────
420
421 async function doWriteStreamOutput(options: {
422 storage: DurableObjectStorage;
423 cacheKey: string;
424 attempt: number;
425 stream: ReadableStream<unknown>;
426 chunkSizeBytes?: number;
427 signal?: AbortSignal;
428 skipMetaWrite?: boolean;
429 }): Promise<StreamOutputMeta> {
430 const { storage, cacheKey, attempt, stream, signal, skipMetaWrite } = options;
431 const chunkSizeBytes = options.chunkSizeBytes ?? DEFAULT_STREAM_OUTPUT_CHUNK_SIZE;
432 const metaKey = getStreamOutputMetaKey(cacheKey);
433
434 const maybeInvalidState = (additionalBytes = 0): unknown => {
435 if (signal?.aborted) {
436 return signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
437 }
438
439 const currentStorageBytes = storage.sql.databaseSize;
440 if (
441 currentStorageBytes + additionalBytes + STREAM_OUTPUT_STORAGE_WRITE_HEADROOM_BYTES >
442 DO_STORAGE_LIMIT
443 ) {
444 return new StreamOutputStorageLimitError("The instance has exceeded the 1GiB storage limit");
445 }
446 };
447
448 const initialInvalidState = maybeInvalidState();
449 if (initialInvalidState !== undefined) {
450 throw initialInvalidState;
451 }
452
453 const startedAt = Date.now();
454 if (!skipMetaWrite) {
455 await storage.put(metaKey, {
456 version: 1,
457 state: StreamOutputState.Pending,
458 attempt,
459 startedAt,
460 chunkCount: 0,
461 totalBytes: 0,
462 committedAt: null,
463 } satisfies StreamOutputMeta);
464 }
465
466 let chunkCount = 0;
467 let totalBytes = 0;
468 const bufferedChunks: Array<Uint8Array> = [];
469 let bufferedBytes = 0;
470 let outputCommitted = false;
471
472 const flushChunk = async (bytes: Uint8Array) => {
473 const invalidState = maybeInvalidState(bytes.byteLength);
474 if (invalidState !== undefined) {
475 throw invalidState;
476 }
477 // eslint-disable-next-line workers-sdk/no-unsafe-command-execution -- DO SQL exec, not child_process
478 storage.sql.exec(
479 `INSERT INTO ${STREAMING_STEP_CHUNKS_TABLE} (cache_key, attempt, chunk_index, chunk) VALUES (?, ?, ?, ?)`,
480 cacheKey,
481 attempt,
482 chunkCount,
483 bytes,
484 );
485 totalBytes += bytes.byteLength;
486 chunkCount++;
487 };
488
489 try {
490 for await (const bytes of iterateStreamChunks(stream, signal)) {
491 if (bytes.byteLength === 0) {
492 continue;
493 }
494
495 if (bytes.byteLength > MAX_STREAM_OUTPUT_INPUT_CHUNK_BYTES) {
496 throw createOversizedStreamChunkError();
497 }
498
499 bufferedChunks.push(bytes);
500 bufferedBytes += bytes.byteLength;
501
502 // NOTE: we want chunks with fixed length,
503 // that's why we buffer them in-memory here
504 while (bufferedBytes >= chunkSizeBytes) {
505 const chunk = takeBufferedBytes(bufferedChunks, chunkSizeBytes);
506 bufferedBytes -= chunk.byteLength;
507 await flushChunk(chunk);
508 }
509 }
510
511 // Last chunk (remainder)
512 if (bufferedBytes > 0) {
513 await flushChunk(takeBufferedBytes(bufferedChunks, bufferedBytes));
514 bufferedBytes = 0;
515 }
516
517 const meta = {
518 version: 1,
519 state: StreamOutputState.Complete,
520 attempt,
521 startedAt,
522 chunkCount,
523 totalBytes,
524 committedAt: Date.now(),
525 } satisfies StreamOutputMeta;
526
527 const invalidState = maybeInvalidState();
528 if (invalidState !== undefined) {
529 throw invalidState;
530 }
531
532 if (!skipMetaWrite) {
533 // Transition to Committing to signal it's safe to await.
534 // Mock stream setup still needs the SQL chunks and returned meta, but
535 // must not publish the normal stream cache key because Context.do()
536 // treats it as a completed prior run and skips step execution logging.
537 await storage.put(metaKey, {
538 version: 1,
539 state: StreamOutputState.Committing,
540 attempt,
541 startedAt,
542 chunkCount,
543 totalBytes,
544 committedAt: null,
545 } satisfies StreamOutputMeta);
546
547 await storage.put(metaKey, meta);
548 }
549 outputCommitted = true;
550 return meta;
551 } catch (error) {
552 if (!outputCommitted) {
553 await rollbackStreamOutput(storage, cacheKey, attempt);
554 }
555 throw error;
556 }
557 }
558
559 export async function writeStreamOutput(options: {
560 storage: DurableObjectStorage;
561 cacheKey: string;
562 attempt: number;
563 stream: ReadableStream<unknown>;
564 chunkSizeBytes?: number;
565 signal?: AbortSignal;
566 timeoutTask?: Promise<never>;
567 skipMetaWrite?: boolean;
568 }): Promise<StreamOutputMeta> {
569 const { storage, cacheKey, attempt, timeoutTask, ...writeOptions } = options;
570 const writeTask = doWriteStreamOutput({
571 storage,
572 cacheKey,
573 attempt,
574 ...writeOptions,
575 });
576
577 if (timeoutTask === undefined) {
578 return writeTask;
579 }
580
581 try {
582 return await Promise.race([writeTask, timeoutTask]);
583 } catch (error) {
584 if (error instanceof WorkflowTimeoutError) {
585 if (options.skipMetaWrite) {
586 void writeTask.catch(() => {});
587 throw error;
588 }
589
590 const maybeMeta = await storage.get<StreamOutputMeta>(getStreamOutputMetaKey(cacheKey));
591 if (
592 maybeMeta?.attempt === attempt &&
593 (maybeMeta.state === StreamOutputState.Committing ||
594 maybeMeta.state === StreamOutputState.Complete)
595 ) {
596 // Safe to await -- not in the middle of writing chunks
597 return await writeTask;
598 }
599
600 void writeTask.catch(() => {});
601 throw error;
602 }
603
604 throw error;
605 }
606 }
607
608 // ── Replay ──────────────────────────────────────────────────────────────────
609
610 export function createReplayReadableStream(options: {
611 storage: DurableObjectStorage;
612 cacheKey: string;
613 meta: StreamOutputMeta;
614 }): ReadableStream<Uint8Array> {
615 const { storage, cacheKey, meta } = options;
616 if (meta.state !== StreamOutputState.Complete) {
617 throw new Error("Cannot replay streamed step output before it is complete");
618 }
619
620 // eslint-disable-next-line workers-sdk/no-unsafe-command-execution -- DO SQL exec, not child_process
621 const chunkCursor = storage.sql.exec<{
622 chunk_index: number;
623 chunk: ArrayBuffer;
624 }>(
625 `SELECT chunk_index, chunk FROM ${STREAMING_STEP_CHUNKS_TABLE} WHERE cache_key = ? AND attempt = ? ORDER BY chunk_index`,
626 cacheKey,
627 meta.attempt,
628 );
629 let index = 0;
630
631 return new ReadableStream<Uint8Array>({
632 pull(controller) {
633 if (index >= meta.chunkCount) {
634 controller.close();
635 return;
636 }
637
638 const row = chunkCursor.next();
639 if (row.done) {
640 controller.error(new Error(`Missing chunk ${index} for streamed step output`));
641 return;
642 }
643
644 if (row.value.chunk_index !== index) {
645 controller.error(new Error(`Missing chunk ${index} for streamed step output`));
646 return;
647 }
648
649 if (!(row.value.chunk instanceof ArrayBuffer)) {
650 controller.error(new Error("Invalid chunk type returned from streaming_step_chunks table"));
651 return;
652 }
653
654 controller.enqueue(new Uint8Array(row.value.chunk));
655 index++;
656 },
657 });
658 }