@agent-os-sdk/client 0.3.15 → 0.4.1

package/src/client/config.ts

@@ -0,0 +1,100 @@
+/**
+ * Agent OS SDK - Network Configuration
+ * 
+ * Centralized configuration for timeouts, retries, and network policies.
+ */
+
+/**
+ * Retry configuration for network requests.
+ */
+export interface RetryConfig {
+    /** Maximum retry attempts (default: 3) */
+    maxRetries: number;
+
+    /** Base delay between retries in ms (default: 1000) */
+    baseDelayMs: number;
+
+    /** Maximum delay between retries in ms (default: 30000) */
+    maxDelayMs: number;
+
+    /** Jitter factor to prevent thundering herd (0-1, default: 0.2) */
+    jitterFactor: number;
+
+    /** HTTP status codes that trigger retry (default: [408, 429, 500, 502, 503, 504]) */
+    retryableStatuses: number[];
+}
+
+/**
+ * Full network configuration for the SDK client.
+ */
+export interface NetworkConfig {
+    /** Timeout per request attempt in milliseconds (default: 30000) */
+    timeoutMs: number;
+
+    /** Retry configuration */
+    retry: RetryConfig;
+}
+
+/**
+ * Default network configuration.
+ * Balanced for most use cases - 30s timeout, 3 retries with exponential backoff.
+ */
+export const DEFAULT_NETWORK_CONFIG: NetworkConfig = {
+    timeoutMs: 30_000,
+    retry: {
+        maxRetries: 3,
+        baseDelayMs: 1_000,
+        maxDelayMs: 30_000,
+        jitterFactor: 0.2,
+        retryableStatuses: [408, 429, 500, 502, 503, 504],
+    },
+};
+
+/**
+ * Aggressive configuration for interactive UIs.
+ * Shorter timeouts, fewer retries.
+ */
+export const INTERACTIVE_NETWORK_CONFIG: NetworkConfig = {
+    timeoutMs: 10_000,
+    retry: {
+        maxRetries: 1,
+        baseDelayMs: 500,
+        maxDelayMs: 5_000,
+        jitterFactor: 0.1,
+        retryableStatuses: [429, 503, 504],
+    },
+};
+
+/**
+ * Patient configuration for background jobs.
+ * Longer timeouts, more retries.
+ */
+export const BACKGROUND_NETWORK_CONFIG: NetworkConfig = {
+    timeoutMs: 120_000,
+    retry: {
+        maxRetries: 5,
+        baseDelayMs: 2_000,
+        maxDelayMs: 60_000,
+        jitterFactor: 0.3,
+        retryableStatuses: [408, 429, 500, 502, 503, 504],
+    },
+};
+
+/**
+ * Merges user config with defaults.
+ */
+export function mergeNetworkConfig(
+    userConfig?: Partial<NetworkConfig>
+): NetworkConfig {
+    if (!userConfig) {
+        return DEFAULT_NETWORK_CONFIG;
+    }
+
+    return {
+        timeoutMs: userConfig.timeoutMs ?? DEFAULT_NETWORK_CONFIG.timeoutMs,
+        retry: {
+            ...DEFAULT_NETWORK_CONFIG.retry,
+            ...userConfig.retry,
+        },
+    };
+}

package/src/client/pagination.ts

@@ -0,0 +1,218 @@
+/**
+ * Agent OS SDK - Pagination Utilities
+ * 
+ * Auto-paginating iterators that support both offset and cursor pagination.
+ * Designed to work with any list endpoint.
+ */
+
+import type { APIResponse } from "./raw.js";
+
+// ============================================================================
+// Response Types
+// ============================================================================
+
+/**
+ * Offset-based paginated response.
+ * Most common format for list endpoints.
+ */
+export interface OffsetPaginatedResponse<T> {
+    items: T[];
+    total: number;
+}
+
+/**
+ * Cursor-based paginated response.
+ * Better for large datasets and real-time consistency.
+ */
+export interface CursorPaginatedResponse<T> {
+    items: T[];
+    next_cursor?: string;
+    has_more: boolean;
+}
+
+/**
+ * Union type for both pagination styles.
+ */
+export type PaginatedResponse<T> =
+    | OffsetPaginatedResponse<T>
+    | CursorPaginatedResponse<T>;
+
+// ============================================================================
+// Parameter Types
+// ============================================================================
+
+/**
+ * Offset pagination parameters.
+ */
+export interface OffsetParams {
+    limit?: number;
+    offset?: number;
+}
+
+/**
+ * Cursor pagination parameters.
+ */
+export interface CursorParams {
+    limit?: number;
+    after?: string;
+}
+
+/**
+ * Combined pagination parameters.
+ */
+export type PaginationParams = OffsetParams | CursorParams;
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+/**
+ * Checks if response uses cursor pagination.
+ */
+function isCursorResponse<T>(response: PaginatedResponse<T>): response is CursorPaginatedResponse<T> {
+    return "has_more" in response;
+}
+
+// ============================================================================
+// Paginate Function
+// ============================================================================
+
+/**
+ * Options for pagination behavior.
+ */
+export interface PaginateOptions {
+    /** Number of items per page (default: 100) */
+    pageSize?: number;
+
+    /** Maximum total items to fetch (default: unlimited) */
+    maxItems?: number;
+
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+
+/**
+ * Creates an async iterator that automatically paginates through results.
+ * Supports both offset and cursor pagination transparently.
+ * 
+ * @example
+ * // Basic usage
+ * for await (const run of paginate(
+ *     (p) => client.runs.list(p),
+ *     { status: "completed" }
+ * )) {
+ *     console.log(run.id);
+ * }
+ * 
+ * @example
+ * // With options
+ * for await (const agent of paginate(
+ *     (p) => client.agents.list(p),
+ *     { workspace_id: "ws_123" },
+ *     { pageSize: 50, maxItems: 200 }
+ * )) {
+ *     console.log(agent.name);
+ * }
+ */
+export async function* paginate<T, P extends PaginationParams>(
+    fetchPage: (params: P) => Promise<APIResponse<PaginatedResponse<T>>>,
+    baseParams: Omit<P, "limit" | "offset" | "after">,
+    options?: PaginateOptions
+): AsyncGenerator<T, void, unknown> {
+    const pageSize = options?.pageSize ?? 100;
+    const maxItems = options?.maxItems ?? Infinity;
+    const signal = options?.signal;
+
+    let offset = 0;
+    let cursor: string | undefined;
+    let hasMore = true;
+    let yielded = 0;
+
+    while (hasMore && yielded < maxItems) {
+        // Check for cancellation
+        if (signal?.aborted) {
+            return;
+        }
+
+        // Build params based on pagination style
+        const params = {
+            ...baseParams,
+            limit: Math.min(pageSize, maxItems - yielded),
+            ...(cursor !== undefined ? { after: cursor } : { offset }),
+        } as P;
+
+        const response = await fetchPage(params);
+
+        if (response.error) {
+            throw response.error;
+        }
+
+        const data = response.data!;
+
+        for (const item of data.items) {
+            if (yielded >= maxItems) {
+                return;
+            }
+            yield item;
+            yielded++;
+        }
+
+        // Update pagination state based on response type
+        if (isCursorResponse(data)) {
+            cursor = data.next_cursor;
+            hasMore = data.has_more && data.items.length > 0;
+        } else {
+            offset += data.items.length;
+            hasMore = offset < data.total && data.items.length > 0;
+        }
+    }
+}
+
+// ============================================================================
+// Collect Utility
+// ============================================================================
+
+/**
+ * Collects all items from a paginated endpoint into an array.
+ * Useful when you need all items at once.
+ * 
+ * @example
+ * const allRuns = await collectAll(
+ *     (p) => client.runs.list(p),
+ *     { status: "completed" },
+ *     { maxItems: 1000 }
+ * );
+ */
+export async function collectAll<T, P extends PaginationParams>(
+    fetchPage: (params: P) => Promise<APIResponse<PaginatedResponse<T>>>,
+    baseParams: Omit<P, "limit" | "offset" | "after">,
+    options?: PaginateOptions
+): Promise<T[]> {
+    const items: T[] = [];
+
+    for await (const item of paginate(fetchPage, baseParams, options)) {
+        items.push(item);
+    }
+
+    return items;
+}
+
+/**
+ * Gets the first item from a paginated endpoint.
+ * More efficient than collecting all items when you only need one.
+ * 
+ * @example
+ * const latestRun = await getFirst(
+ *     (p) => client.runs.list({ ...p, order: "desc" }),
+ *     { agent_id: "agent_123" }
+ * );
+ */
+export async function getFirst<T, P extends PaginationParams>(
+    fetchPage: (params: P) => Promise<APIResponse<PaginatedResponse<T>>>,
+    baseParams: Omit<P, "limit" | "offset" | "after">
+): Promise<T | undefined> {
+    for await (const item of paginate(fetchPage, baseParams, { pageSize: 1, maxItems: 1 })) {
+        return item;
+    }
+    return undefined;
+}

package/src/client/raw.ts

@@ -5,18 +5,57 @@
  * All types are automatically inferred from the backend Swagger specification.
  */
 
-import createClient, { type Client, type FetchOptions } from "openapi-fetch";
-import type { paths, components } from "../generated/openapi.js";
+import createClient, { type Client } from "openapi-fetch";
+import type { components, paths } from "../generated/openapi.js";
 
 // Re-export types for external use
-export type { paths, components };
+export type { components, paths };
 
 export type ClientOptions = {
     baseUrl: string;
     headers?: Record<string, string>;
     headerProvider?: () => Promise<Record<string, string>>;
+    /** Hooks for observability (OTEL, Sentry, etc.) */
+    hooks?: SDKHooks;
 };
 
+/**
+ * SDK hooks for external observability tools.
+ * These are called during the request lifecycle for instrumentation.
+ */
+export interface SDKHooks {
+    /** Called before each request. Return modified request context or void. */
+    onRequest?: (context: HookRequestContext) => void | Promise<void>;
+    /** Called after each successful response */
+    onResponse?: (context: HookResponseContext) => void | Promise<void>;
+    /** Called on any error (network, timeout, HTTP error) */
+    onError?: (context: HookErrorContext) => void | Promise<void>;
+}
+
+export interface HookRequestContext {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: unknown;
+    requestId?: string;
+}
+
+export interface HookResponseContext {
+    method: string;
+    url: string;
+    status: number;
+    durationMs: number;
+    requestId?: string;
+}
+
+export interface HookErrorContext {
+    method: string;
+    url: string;
+    error: Error;
+    durationMs: number;
+    requestId?: string;
+}
+
 /**
  * Standard API response wrapper.
  * This matches the pattern used by openapi-fetch.
@@ -29,6 +68,11 @@ export interface APIResponse<T> {
         details?: unknown;
     };
     response: Response;
+    /** Metadata for observability */
+    meta?: {
+        /** Request ID from x-request-id header */
+        requestId?: string;
+    };
 }
 
 /**
@@ -62,6 +106,11 @@ export function createRawClient(options: ClientOptions) {
             params?: { path?: Record<string, string>; query?: Record<string, unknown> };
             body?: unknown;
             headers?: Record<string, string>;
+            signal?: AbortSignal;
+            /** Set to false to disable retry for this request */
+            retry?: boolean;
+            /** Override timeout for this request */
+            timeoutMs?: number;
         }
     ): Promise<APIResponse<T>> {
         // Replace path params
@@ -103,40 +152,112 @@ export function createRawClient(options: ClientOptions) {
             headers["Content-Type"] = "application/json";
         }
 
-        const response = await fetch(fullUrl, {
+        // Detect idempotency from header or body
+        const hasIdempotencyKey = Boolean(
+            headers["Idempotency-Key"] ||
+            headers["idempotency-key"] ||
+            (opts?.body && typeof opts.body === "object" && (opts.body as Record<string, unknown>).idempotency_key)
+        );
+
+        // Generate client request ID for tracing
+        const clientRequestId = `sdk_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+
+        // Call onRequest hook
+        const startTime = Date.now();
+        await options.hooks?.onRequest?.({
             method,
+            url: fullUrl,
             headers,
-            body: opts?.body ? JSON.stringify(opts.body) : undefined,
+            body: opts?.body,
+            requestId: clientRequestId,
         });
 
+        // Execute the actual fetch
+        const doFetch = async (signal?: AbortSignal): Promise<Response> => {
+            return fetch(fullUrl, {
+                method,
+                headers,
+                body: opts?.body ? JSON.stringify(opts.body) : undefined,
+                signal,
+            });
+        };
+
+        let response: Response;
+        try {
+            response = await doFetch(opts?.signal);
+        } catch (fetchError) {
+            const durationMs = Date.now() - startTime;
+            // Call onError hook
+            await options.hooks?.onError?.({
+                method,
+                url: fullUrl,
+                error: fetchError instanceof Error ? fetchError : new Error(String(fetchError)),
+                durationMs,
+                requestId: clientRequestId,
+            });
+
+            // Network error - return as error
+            return {
+                error: {
+                    code: "NETWORK_ERROR",
+                    message: fetchError instanceof Error ? fetchError.message : "Network request failed"
+                },
+                response: new Response(null, { status: 503, statusText: "Network Error" })
+            };
+        }
+
+        const durationMs = Date.now() - startTime;
+
+        // Extract requestId for tracing (prefer server requestId if available)
+        const requestId = response.headers.get("x-request-id") ?? clientRequestId;
+
         if (!response.ok) {
-            let error: APIResponse<T>["error"];
+            let errorBody: { code?: string; message?: string; details?: unknown } | undefined;
             try {
-                const json = await response.json();
-                error = {
-                    code: json.code || `HTTP_${response.status}`,
-                    message: json.message || response.statusText,
-                    details: json.details,
-                };
+                errorBody = await response.json();
             } catch {
-                error = {
-                    code: `HTTP_${response.status}`,
-                    message: response.statusText,
-                };
+                // Ignore JSON parse errors
             }
-            return { error, response };
+
+            // Call onError hook
+            await options.hooks?.onError?.({
+                method,
+                url: fullUrl,
+                error: new Error(errorBody?.message || response.statusText),
+                durationMs,
+                requestId,
+            });
+
+            return {
+                error: {
+                    code: errorBody?.code || `HTTP_${response.status}`,
+                    message: errorBody?.message || response.statusText,
+                    details: errorBody?.details,
+                },
+                response,
+                meta: { requestId },
+            };
         }
 
+        // Call onResponse hook
+        await options.hooks?.onResponse?.({
+            method,
+            url: fullUrl,
+            status: response.status,
+            durationMs,
+            requestId,
+        });
+
         // Handle no-content responses
         if (response.status === 204) {
-            return { data: undefined as T, response };
+            return { data: undefined as T, response, meta: { requestId } };
         }
 
         try {
             const data = await response.json();
-            return { data: data as T, response };
+            return { data: data as T, response, meta: { requestId } };
         } catch {
-            return { data: undefined as T, response };
+            return { data: undefined as T, response, meta: { requestId } };
         }
     }
 

package/src/client/retry.ts

@@ -0,0 +1,150 @@
+/**
+ * Agent OS SDK - Retry Logic
+ * 
+ * Enterprise-grade retry with:
+ * - Exponential backoff with jitter
+ * - Respect for Retry-After headers
+ * - Idempotency-aware mutation retries
+ * - Proper abort signal handling (no listener leaks)
+ */
+
+import { AgentOsError, NetworkError, TimeoutError, RateLimitError } from "../errors/index.js";
+import type { RetryConfig } from "./config.js";
+
+/**
+ * Context for retry decision-making.
+ */
+export interface RetryContext {
+    /** HTTP method (GET, POST, etc.) */
+    method: string;
+
+    /** Whether the request has an idempotency key */
+    hasIdempotencyKey: boolean;
+}
+
+/**
+ * Wraps an async function with retry logic.
+ * 
+ * IMPORTANT: Mutations (POST/PUT/PATCH/DELETE) are only retried if hasIdempotencyKey is true.
+ * This prevents duplicate side effects.
+ * 
+ * @param fn - Function to execute (receives an AbortSignal)
+ * @param config - Retry configuration
+ * @param context - Request context for retry decisions
+ * @param parentSignal - Optional parent AbortSignal for cancellation
+ */
+export async function withRetry<T>(
+    fn: (signal: AbortSignal) => Promise<T>,
+    config: RetryConfig,
+    context: RetryContext,
+    parentSignal?: AbortSignal
+): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+        // Check parent abort before each attempt
+        if (parentSignal?.aborted) {
+            throw new Error("Request aborted");
+        }
+
+        const controller = new AbortController();
+
+        // Proper abort propagation without listener leak
+        const onAbort = () => controller.abort();
+        parentSignal?.addEventListener("abort", onAbort, { once: true });
+
+        try {
+            return await fn(controller.signal);
+        } catch (err) {
+            lastError = err as Error;
+
+            // If parent aborted, don't retry
+            if (controller.signal.aborted && parentSignal?.aborted) {
+                throw err;
+            }
+
+            // Check if this error is retryable
+            if (!shouldRetry(err, config, context)) {
+                throw err;
+            }
+
+            // Last attempt reached
+            if (attempt === config.maxRetries) {
+                throw err;
+            }
+
+            // Rate limit: use Retry-After if available
+            if (err instanceof RateLimitError && err.retryAfterMs) {
+                await sleep(err.retryAfterMs);
+                continue;
+            }
+
+            // Exponential backoff with jitter
+            const delay = calculateBackoff(attempt, config);
+            await sleep(delay);
+        } finally {
+            // CRITICAL: Always cleanup listener to prevent memory leak
+            parentSignal?.removeEventListener("abort", onAbort);
+        }
+    }
+
+    throw lastError ?? new Error("Retry failed");
+}
+
+/**
+ * Determines if an error should trigger a retry.
+ */
+function shouldRetry(
+    err: unknown,
+    config: RetryConfig,
+    context: RetryContext
+): boolean {
+    // Network and timeout errors are always retryable
+    if (err instanceof NetworkError || err instanceof TimeoutError) {
+        return true;
+    }
+
+    // Unknown errors are not retryable
+    if (!(err instanceof AgentOsError)) {
+        return false;
+    }
+
+    // Check if status code is in retryable list
+    if (!config.retryableStatuses.includes(err.status)) {
+        return false;
+    }
+
+    // CRITICAL: Only retry mutations if they have an idempotency key
+    // This prevents duplicate side effects from retrying POST/PUT/PATCH/DELETE
+    const isMutation = !["GET", "HEAD", "OPTIONS"].includes(context.method.toUpperCase());
+    if (isMutation && !context.hasIdempotencyKey) {
+        return false;
+    }
+
+    return true;
+}
+
+/**
+ * Calculates backoff delay with exponential increase and jitter.
+ */
+function calculateBackoff(attempt: number, config: RetryConfig): number {
+    // Exponential backoff: baseDelay * 2^attempt
+    const exponential = config.baseDelayMs * Math.pow(2, attempt);
+
+    // Cap at max delay
+    const capped = Math.min(exponential, config.maxDelayMs);
+
+    // Add jitter to prevent thundering herd
+    const jitter = capped * config.jitterFactor * Math.random();
+
+    return Math.floor(capped + jitter);
+}
+
+/**
+ * Sleep utility.
+ */
+function sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export { sleep };