@stacklink/sdk 0.3.8 → 0.3.10

package/dist/src/sdk/index.js

@@ -1,18 +1,20 @@
 import { botApiSignaturePayload } from '../domain/bot-contract.js';
 import { materializeStacklinkWorkbenchExecutionResponse, } from '../domain/stacklink-meta-tools.js';
 export { StacklinkMemoryLifecycle, StacklinkMemoryLifecycleError, createStacklinkMemoryLifecycle, serializeCompletedConversationTurn, } from './memory-lifecycle.js';
-export const stacklinkTypeScriptSdkVersion = '0.3.8';
+export const stacklinkTypeScriptSdkVersion = '0.3.10';
 const workbenchReusableRunComparisonWaitMs = 120_000;
 const workbenchReusableRunComparisonPollMs = 1_000;
 export class StacklinkApiError extends Error {
     statusCode;
     code;
     details;
-    constructor(message, statusCode, code, details) {
+    retryAfterMs;
+    constructor(message, statusCode, code, details, retryAfterMs) {
         super(message);
         this.statusCode = statusCode;
         this.code = code;
         this.details = details;
+        this.retryAfterMs = retryAfterMs;
         this.name = 'StacklinkApiError';
     }
 }
@@ -835,48 +837,66 @@ export class Stacklink {
     }
     async *streamExecutionEvents(input, options = {}) {
         let afterSequence = input.afterSequence === undefined ? undefined : String(input.afterSequence);
-        while (!options.signal?.aborted) {
-            const response = await this.requestRaw(`/v1/executions/${input.executionKind}/${input.executionId}/events/stream`, {
-                headers: {
-                    accept: 'text/event-stream',
-                    ...(afterSequence === undefined ? {} : { 'Last-Event-ID': afterSequence }),
-                },
-                query: {
-                    sessionId: input.sessionId,
-                    afterSequence,
-                    limit: input.limit,
-                },
-                signal: options.signal,
-                timeoutMs: options.timeoutMs ?? 30_000,
-            });
+        const totalTimeoutMs = positiveSdkInteger(options.totalTimeoutMs ?? 3_600_000, 'totalTimeoutMs');
+        const maxReconnectAttempts = positiveSdkInteger(options.maxReconnectAttempts ?? 8, 'maxReconnectAttempts');
+        const deadline = Date.now() + totalTimeoutMs;
+        const observationSignal = AbortSignal.timeout(totalTimeoutMs);
+        const signal = options.signal ? AbortSignal.any([options.signal, observationSignal]) : observationSignal;
+        let failures = 0;
+        while (!signal.aborted) {
+            let delayMs = sdkRetryDelayMs(undefined, failures + 1);
             try {
-                for await (const payload of this.readJsonEventStream(response)) {
-                    if (!isSdkRecord(payload))
-                        continue;
-                    const events = Array.isArray(payload.events) ? payload.events : [];
-                    for (const event of events) {
-                        if (isSdkRecord(event) && (typeof event.sequence === 'string' || typeof event.sequence === 'number')) {
-                            afterSequence = String(event.sequence);
+                const connectionSignal = AbortSignal.any([signal, AbortSignal.timeout(Math.min(options.timeoutMs ?? 30_000, Math.max(1, deadline - Date.now())))]);
+                const response = await this.requestRaw(`/v1/executions/${input.executionKind}/${input.executionId}/events/stream`, { headers: { accept: 'text/event-stream', ...(afterSequence === undefined ? {} : { 'Last-Event-ID': afterSequence }) },
+                    query: { sessionId: input.sessionId, afterSequence, limit: input.limit },
+                    signal, timeoutMs: Math.min(options.timeoutMs ?? 30_000, Math.max(1, deadline - Date.now())) });
+                for await (const payload of this.readJsonEventStream(response, connectionSignal)) {
+                    if (!isSdkRecord(payload) || !Array.isArray(payload.events)) {
+                        throw new StacklinkApiError('Execution stream returned an invalid event page.', 502, 'execution_event_invalid');
+                    }
+                    failures = 0;
+                    for (const event of payload.events) {
+                        if (!isSdkRecord(event) || (typeof event.sequence !== 'string' && typeof event.sequence !== 'number')) {
+                            throw new StacklinkApiError('Execution event has no durable sequence.', 502, 'execution_event_invalid');
                         }
+                        const sequence = BigInt(event.sequence);
+                        if (afterSequence !== undefined && sequence <= BigInt(afterSequence))
+                            continue;
+                        afterSequence = String(event.sequence);
                         yield event;
                     }
-                    if (typeof payload.nextCursor === 'string')
+                    if (typeof payload.nextCursor === 'string' && (afterSequence === undefined || BigInt(payload.nextCursor) > BigInt(afterSequence)))
                         afterSequence = payload.nextCursor;
                     if (payload.terminal === true)
                         return;
                 }
             }
             catch (error) {
-                if (options.signal?.aborted)
-                    throw options.signal.reason ?? error;
-                const errorName = error instanceof Error ? error.name : '';
-                if (errorName !== 'AbortError' && errorName !== 'TimeoutError')
+                if (signal.aborted)
+                    break;
+                const retryable = error instanceof TypeError
+                    || (error instanceof Error && ['AbortError', 'TimeoutError'].includes(error.name))
+                    || (error instanceof StacklinkApiError && sdkRetryableStatus(error.statusCode) && error.code !== 'execution_event_invalid');
+                if (!retryable)
                     throw error;
-                // The per-connection deadline bounds a stream. Reconnect from the durable cursor.
+                if (error instanceof StacklinkApiError && error.retryAfterMs !== undefined)
+                    delayMs = error.retryAfterMs;
+            }
+            failures += 1;
+            if (failures > maxReconnectAttempts)
+                throw new StacklinkApiError('Execution observation could not reconnect. Resume this execution from the saved cursor.', 503, 'sdk_stream_reconnect_exhausted', { executionId: input.executionId, afterSequence });
+            if (delayMs >= deadline - Date.now())
+                break;
+            try {
+                await sdkDelay(delayMs, signal);
+            }
+            catch {
+                break;
             }
         }
         if (options.signal?.aborted)
             throw options.signal.reason ?? new Error('Stacklink execution stream was aborted.');
+        throw new StacklinkApiError('Execution observation reached its deadline. The operation has not been resubmitted or cancelled.', 408, 'sdk_stream_observation_timeout', { executionId: input.executionId, afterSequence });
     }
     async waitForExecution(input, options = {}) {
         return this.request(`/v1/executions/${input.executionKind}/${input.executionId}/wait`, {
@@ -1486,7 +1506,7 @@ export class Stacklink {
             catch {
                 parsed = null;
             }
-            throw new StacklinkApiError(isSdkRecord(parsed) && typeof parsed.message === 'string' ? parsed.message : `Stacklink request failed with ${response.status}`, response.status, isSdkRecord(parsed) && typeof parsed.code === 'string' ? parsed.code : undefined, isSdkRecord(parsed) ? parsed.details : undefined);
+            throw new StacklinkApiError(isSdkRecord(parsed) && typeof parsed.message === 'string' ? parsed.message : `Stacklink request failed with ${response.status}`, response.status, isSdkRecord(parsed) && typeof parsed.code === 'string' ? parsed.code : undefined, isSdkRecord(parsed) ? parsed.details : undefined, response.headers.has('retry-after') ? sdkRetryDelayMs(response, 1) : undefined);
         }
         return response;
     }
@@ -1677,10 +1697,12 @@ export class Stacklink {
             reader.releaseLock();
         }
     }
-    async *readJsonEventStream(response) {
+    async *readJsonEventStream(response, signal) {
         if (!response.body)
             throw new Error('Stacklink event stream response has no body.');
         const reader = response.body.getReader();
+        const abortRead = () => { void reader.cancel(signal?.reason).catch(() => undefined); };
+        signal?.addEventListener('abort', abortRead, { once: true });
         const decoder = new TextDecoder();
         let buffer = '';
         let dataLines = [];
@@ -1705,7 +1727,9 @@ export class Stacklink {
         };
         try {
             while (true) {
+                signal?.throwIfAborted();
                 const read = await reader.read();
+                signal?.throwIfAborted();
                 if (read.done)
                     break;
                 buffer += decoder.decode(read.value, { stream: true });
@@ -1729,6 +1753,7 @@ export class Stacklink {
                 yield finalPayload;
         }
         finally {
+            signal?.removeEventListener('abort', abortRead);
             await reader.cancel().catch(() => undefined);
             reader.releaseLock();
         }
@@ -2394,9 +2419,12 @@ export class StacklinkWorkbenchRun {
             executionKind: this.executionKind,
             executionId: this.executionId,
             limit: input.limit ?? 200,
+            afterSequence: input.afterSequence,
         }, {
             signal: input.signal,
             timeoutMs: input.streamTimeoutMs,
+            totalTimeoutMs: input.totalTimeoutMs,
+            maxReconnectAttempts: input.maxReconnectAttempts,
         });
     }
     wait(input = {}) {