@agent-os-sdk/client 0.3.15 → 0.4.0

package/src/modules/runs.ts

@@ -103,16 +103,31 @@ export class RunsModule {
      *   agent_id: "agent-uuid",
      *   input: { message: "Hello" }
      * });
+     * 
+     * // With idempotency (safe to retry)
+     * const { data } = await client.runs.create({
+     *   agent_id: "agent-uuid",
+     *   input: { message: "Hello" },
+     *   idempotency_key: "my-unique-key"
+     * });
      * ```
      */
     async create(body: {
         agent_id: string;
         thread?: { thread_id?: string } | { new_thread: true };
         input?: unknown;
+        /** Idempotency key for safe retries. When set, duplicate requests with the same key return the original response. */
         idempotency_key?: string;
     }): Promise<APIResponse<CreateRunResponse>> {
+        // Send Idempotency-Key in HEADER (enterprise standard) + body (backend compat)
+        const headers: Record<string, string> = {};
+        if (body.idempotency_key) {
+            headers["Idempotency-Key"] = body.idempotency_key;
+        }
+
         return this.client.POST<CreateRunResponse>("/v1/api/runs", {
             body,
+            headers,
         });
     }
 
@@ -138,6 +153,59 @@ export class RunsModule {
         });
     }
 
+    /**
+     * Iterate through all runs with automatic pagination.
+     * 
+     * @example
+     * ```ts
+     * // Stream all completed runs
+     * for await (const run of client.runs.iterate({ status: "completed" })) {
+     *     console.log(run.run_id, run.status);
+     * }
+     * 
+     * // With limit
+     * for await (const run of client.runs.iterate({ agent_id: "..." }, { maxItems: 100 })) {
+     *     processRun(run);
+     * }
+     * ```
+     */
+    async *iterate(
+        filters?: {
+            thread_id?: string;
+            agent_id?: string;
+            status?: string;
+        },
+        options?: { pageSize?: number; maxItems?: number; signal?: AbortSignal }
+    ): AsyncGenerator<Run, void, unknown> {
+        const pageSize = options?.pageSize ?? 100;
+        const maxItems = options?.maxItems ?? Infinity;
+        let offset = 0;
+        let yielded = 0;
+        let hasMore = true;
+
+        while (hasMore && yielded < maxItems) {
+            if (options?.signal?.aborted) return;
+
+            const response = await this.list({
+                ...filters,
+                limit: Math.min(pageSize, maxItems - yielded),
+                offset,
+            });
+
+            if (response.error) throw response.error;
+            const data = response.data!;
+
+            for (const run of data.items) {
+                if (yielded >= maxItems) return;
+                yield run;
+                yielded++;
+            }
+
+            offset += data.items.length;
+            hasMore = offset < data.total && data.items.length > 0;
+        }
+    }
+
     // ======================== Execution ========================
 
     /**
@@ -376,4 +444,269 @@ export class RunsModule {
         });
         yield* parseSSE<RunStreamEvent>(response, { onOpen: options?.onOpen });
     }
+
+    // ======================== FOLLOW (Enterprise SSE) ========================
+
+    /**
+     * Follow a run's event stream with automatic reconnection and resume.
+     * 
+     * This is the enterprise-grade streaming method that:
+     * - Reconnects automatically on connection drops
+     * - Resumes from last received event using Last-Event-ID
+     * - Never duplicates or loses events
+     * - Terminates cleanly on 'close' event
+     * 
+     * @example
+     * ```ts
+     * for await (const event of client.runs.follow(runId)) {
+     *     if (event.type === "run_event") {
+     *         console.log(event.payload);
+     *     } else if (event.type === "close") {
+     *         console.log("Run completed");
+     *     }
+     * }
+     * ```
+     */
+    async *follow(runId: string, options?: FollowOptions): AsyncGenerator<FollowEvent, void, unknown> {
+        const signal = options?.signal;
+        const maxReconnects = options?.maxReconnects ?? 10;
+        const baseDelayMs = options?.baseDelayMs ?? 1000;
+        const maxDelayMs = options?.maxDelayMs ?? 30000;
+
+        // nextSeq = next seq we expect to receive (or 0 at start)
+        let nextSeq = options?.startSeq ?? 0;
+        let reconnectCount = 0;
+        let receivedTerminal = false;
+
+        options?.onConnect?.();
+
+        while (!receivedTerminal && reconnectCount <= maxReconnects) {
+            if (signal?.aborted) return;
+
+            try {
+                // Build headers - Last-Event-ID is the LAST seq we received (nextSeq - 1)
+                const headers: Record<string, string> = {};
+                if (nextSeq > 0) {
+                    headers["Last-Event-ID"] = String(nextSeq - 1);
+                }
+
+                const response = await this.client.streamGet("/v1/api/runs/{runId}/stream", {
+                    params: {
+                        path: { runId },
+                        query: nextSeq > 0 ? { seq: nextSeq } : undefined  // Also send as query for backends that support it
+                    },
+                    headers,
+                });
+
+                // Check for auth errors - don't reconnect on these
+                if (response.status === 401 || response.status === 403) {
+                    const errorEvent: FollowEvent = {
+                        type: "error",
+                        payload: { code: `HTTP_${response.status}`, message: response.statusText },
+                        seq: -1,
+                        timestamp: new Date().toISOString(),
+                    };
+                    yield errorEvent;
+                    return; // Don't reconnect on auth errors
+                }
+
+                if (!response.ok) {
+                    throw new Error(`SSE connection failed: ${response.status}`);
+                }
+
+                // Reset reconnect count on successful connection
+                if (reconnectCount > 0) {
+                    options?.onReconnect?.(reconnectCount);
+                }
+                reconnectCount = 0;
+
+                // Parse SSE stream
+                for await (const rawEvent of parseSSE<unknown>(response)) {
+                    if (signal?.aborted) return;
+
+                    // Narrow to known event types
+                    const event = narrowFollowEvent(rawEvent);
+                    if (!event) continue; // Skip unknown event types
+
+                    // Update seq tracking if event has seq
+                    if (typeof event.seq === "number" && event.seq >= 0) {
+                        nextSeq = event.seq + 1;
+                    }
+
+                    // Check for terminal events
+                    if (event.type === "close") {
+                        receivedTerminal = true;
+                        yield event;
+                        return;
+                    }
+
+                    if (event.type === "error") {
+                        // Error event from server - yield but continue (might reconnect)
+                        yield event;
+                        // If it's a fatal error, break and try reconnect
+                        break;
+                    }
+
+                    yield event;
+                }
+
+                // Stream ended without close event - this is unexpected EOF
+                // Reconnect unless we already received terminal
+                if (!receivedTerminal && !signal?.aborted) {
+                    options?.onDisconnect?.("eof");
+                    reconnectCount++;
+                    if (reconnectCount <= maxReconnects) {
+                        await sleep(calculateBackoff(reconnectCount, baseDelayMs, maxDelayMs));
+                    }
+                }
+
+            } catch (err) {
+                if (signal?.aborted) return;
+
+                options?.onDisconnect?.("error");
+                reconnectCount++;
+
+                if (reconnectCount <= maxReconnects) {
+                    await sleep(calculateBackoff(reconnectCount, baseDelayMs, maxDelayMs));
+                } else {
+                    // Max reconnects exceeded - yield error and stop
+                    yield {
+                        type: "error",
+                        payload: { code: "MAX_RECONNECTS", message: `Max reconnects (${maxReconnects}) exceeded` },
+                        seq: -1,
+                        timestamp: new Date().toISOString(),
+                    };
+                    return;
+                }
+            }
+        }
+    }
+
+    /**
+     * Wait for a specific event that matches a predicate.
+     * 
+     * @example
+     * ```ts
+     * // Wait for run completion
+     * const event = await client.runs.waitFor(runId, (e) => e.type === "close", {
+     *     timeoutMs: 60000
+     * });
+     * 
+     * // Wait for specific node execution
+     * const nodeEvent = await client.runs.waitFor(runId, (e) => 
+     *     e.type === "run_event" && e.payload?.node === "my_node"
+     * );
+     * ```
+     */
+    async waitFor(
+        runId: string,
+        predicate: (event: FollowEvent) => boolean,
+        options?: { timeoutMs?: number; signal?: AbortSignal; startSeq?: number }
+    ): Promise<FollowEvent> {
+        const timeoutMs = options?.timeoutMs ?? 300_000; // 5 min default
+        const controller = new AbortController();
+
+        // Combine parent signal with our timeout
+        const onAbort = () => controller.abort();
+        options?.signal?.addEventListener("abort", onAbort, { once: true });
+
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+        try {
+            for await (const event of this.follow(runId, {
+                signal: controller.signal,
+                startSeq: options?.startSeq,
+            })) {
+                if (predicate(event)) {
+                    return event;
+                }
+
+                // If we got close without matching predicate, error
+                if (event.type === "close") {
+                    throw new Error("Run completed without matching event");
+                }
+            }
+
+            // Stream ended without match or terminal
+            throw new Error("Stream ended without matching event");
+
+        } catch (err) {
+            if (controller.signal.aborted && !options?.signal?.aborted) {
+                // Our timeout triggered the abort
+                const { TimeoutError } = await import("../errors/index.js");
+                throw new TimeoutError(timeoutMs);
+            }
+            throw err;
+        } finally {
+            clearTimeout(timeoutId);
+            options?.signal?.removeEventListener("abort", onAbort);
+        }
+    }
+}
+
+// ============================================================================
+// Follow Types & Helpers
+// ============================================================================
+
+/** Options for runs.follow() */
+export interface FollowOptions {
+    /** Starting sequence number (default: 0 = from beginning) */
+    startSeq?: number;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** Max reconnection attempts (default: 10) */
+    maxReconnects?: number;
+    /** Base delay for backoff in ms (default: 1000) */
+    baseDelayMs?: number;
+    /** Max delay for backoff in ms (default: 30000) */
+    maxDelayMs?: number;
+    /** Called when initially connected */
+    onConnect?: () => void;
+    /** Called when reconnecting (with attempt number) */
+    onReconnect?: (attempt: number) => void;
+    /** Called when disconnected (with reason) */
+    onDisconnect?: (reason: "eof" | "error") => void;
+}
+
+/** Event emitted by runs.follow() */
+export interface FollowEvent {
+    type: "run_event" | "heartbeat" | "close" | "error";
+    seq: number;
+    timestamp: string;
+    payload?: Record<string, unknown> | null;
+    /** For run_event: the node that emitted this event */
+    node?: string;
+}
+
+/** Narrow raw SSE event to FollowEvent */
+function narrowFollowEvent(raw: SSEEvent<unknown>): FollowEvent | null {
+    const eventType = raw.event ?? "message";
+    const validTypes = ["run_event", "heartbeat", "close", "error"];
+
+    if (!validTypes.includes(eventType)) {
+        return null;
+    }
+
+    const data = raw.data as Record<string, unknown> | null;
+
+    return {
+        type: eventType as FollowEvent["type"],
+        seq: typeof data?.seq === "number" ? data.seq : (raw.id ? parseInt(raw.id, 10) : -1),
+        timestamp: typeof data?.timestamp === "string" ? data.timestamp : new Date().toISOString(),
+        payload: data,
+        node: typeof data?.node === "string" ? data.node : undefined,
+    };
+}
+
+/** Calculate exponential backoff with jitter */
+function calculateBackoff(attempt: number, baseMs: number, maxMs: number): number {
+    const exponential = baseMs * Math.pow(2, attempt - 1);
+    const capped = Math.min(exponential, maxMs);
+    const jitter = capped * 0.2 * Math.random();
+    return Math.floor(capped + jitter);
+}
+
+/** Sleep utility */
+function sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
 }

package/src/modules/tenants.ts

@@ -27,8 +27,11 @@ export class TenantsModule {
     /**
      * List all tenants the user has access to.
      */
-    async list(): Promise<APIResponse<Tenant[]>> {
-        return this.client.GET<Tenant[]>("/v1/api/tenants", {
+    /**
+     * List all tenants the user has access to.
+     */
+    async list(): Promise<APIResponse<TenantListResponse>> {
+        return this.client.GET<TenantListResponse>("/v1/api/tenants", {
             headers: this.headers(),
         });
     }

package/src/modules/threads.ts

@@ -79,16 +79,29 @@ export class ThreadsModule {
      * @example
      * ```ts
      * const { data: thread } = await client.threads.create();
+     * 
+     * // With idempotency (safe to retry)
+     * const { data: thread } = await client.threads.create({
+     *   idempotency_key: "my-unique-key"
+     * });
      * ```
      */
     async create(body?: {
         channel?: string;
         external_conversation_id?: string;
         metadata?: Record<string, unknown>;
+        /** Idempotency key for safe retries. When set, duplicate requests with the same key return the original response. */
+        idempotency_key?: string;
     }): Promise<APIResponse<Thread>> {
+        // Send Idempotency-Key in HEADER (enterprise standard) + body (backend compat)
+        const headers: Record<string, string> = { ...this.headers() };
+        if (body?.idempotency_key) {
+            headers["Idempotency-Key"] = body.idempotency_key;
+        }
+
         return this.client.POST<Thread>("/v1/api/threads", {
             body: body ?? {},
-            headers: this.headers(),
+            headers,
         });
     }
 
@@ -122,6 +135,49 @@ export class ThreadsModule {
         });
     }
 
+    /**
+     * Iterate through all threads with automatic pagination.
+     * 
+     * @example
+     * ```ts
+     * for await (const thread of client.threads.iterate()) {
+     *     console.log(thread.id);
+     * }
+     * ```
+     */
+    async *iterate(
+        filters?: { workspace_id?: string },
+        options?: { pageSize?: number; maxItems?: number; signal?: AbortSignal }
+    ): AsyncGenerator<Thread, void, unknown> {
+        const pageSize = options?.pageSize ?? 100;
+        const maxItems = options?.maxItems ?? Infinity;
+        let offset = 0;
+        let yielded = 0;
+        let hasMore = true;
+
+        while (hasMore && yielded < maxItems) {
+            if (options?.signal?.aborted) return;
+
+            const response = await this.list({
+                ...filters,
+                limit: Math.min(pageSize, maxItems - yielded),
+                offset,
+            });
+
+            if (response.error) throw response.error;
+            const data = response.data!;
+
+            for (const thread of data.items) {
+                if (yielded >= maxItems) return;
+                yield thread;
+                yielded++;
+            }
+
+            offset += data.items.length;
+            hasMore = offset < data.total && data.items.length > 0;
+        }
+    }
+
     /**
      * Delete a thread.
      */

package/src/sse/client.ts

@@ -51,7 +51,10 @@ export async function* parseSSE<T>(
 
     const reader = response.body.getReader();
     const decoder = new TextDecoder();
+
     let buffer = "";
+    // State must be maintained across chunks
+    let currentEvent: Partial<SSEEvent<T>> = { event: "message" };
 
     try {
         while (true) {
@@ -60,16 +63,32 @@ export async function* parseSSE<T>(
 
             buffer += decoder.decode(value, { stream: true });
             const lines = buffer.split("\n");
-            buffer = lines.pop() ?? "";
 
-            let currentEvent: Partial<SSEEvent<T>> = { event: "message" };
+            // Keep the last partial line in the buffer
+            buffer = lines.pop() ?? "";
 
             for (const line of lines) {
+                const trimmed = line.trim();
+
+                if (trimmed === "") {
+                    // Empty line triggers event dispatch if we have data
+                    if (currentEvent.data !== undefined) {
+                        yield currentEvent as SSEEvent<T>;
+                    }
+                    // Reset for next event
+                    currentEvent = { event: "message" };
+                    continue;
+                }
+
                 if (line.startsWith("event:")) {
                     currentEvent.event = line.slice(6).trim();
                 } else if (line.startsWith("data:")) {
                     const dataStr = line.slice(5).trim();
                     try {
+                        // Accumulate data if meaningful (though standard SSE usually has one data line per event, 
+                        // multiline data is possible but rare in this specific protocol. 
+                        // For simplicity and matching current backend, we overwrite or concatenation check could be stricter).
+                        // Given strict JSON protocol, we assume valid info per data line or single data line.
                         currentEvent.data = JSON.parse(dataStr) as T;
                     } catch {
                         currentEvent.data = dataStr as T;
@@ -78,9 +97,6 @@ export async function* parseSSE<T>(
                     currentEvent.id = line.slice(3).trim();
                 } else if (line.startsWith("retry:")) {
                     currentEvent.retry = parseInt(line.slice(6).trim(), 10);
-                } else if (line === "" && currentEvent.data !== undefined) {
-                    yield currentEvent as SSEEvent<T>;
-                    currentEvent = { event: "message" };
                 }
             }
         }