@agent-os-sdk/client 0.9.25 → 0.9.27

package/src/modules/runs.ts

@@ -1,878 +0,0 @@
-/**
- * Runs Module - Core execution API (Fully Typed)
- * 
- * Naming conventions:
- * - get* for singular items
- * - list* for collections  
- * - create*, update*, delete* for mutations
- */
-
-import type { RawClient, APIResponse, components } from "../client/raw.js";
-import type { PaginationParams, PaginatedResponse } from "../client/helpers.js";
-import { parseSSE, type SSEEvent } from "../sse/client.js";
-
-// Type aliases from OpenAPI
-type WaitRunResponse = components["schemas"]["WaitRunResponse"];
-type BatchRunResponse = components["schemas"]["BatchRunResponse"];
-type CancelRunResponse = components["schemas"]["CancelRunResponse"];
-type CheckpointIndexResponse = components["schemas"]["CheckpointIndexResponse"];
-type RunReplayResponse = components["schemas"]["RunReplayResponse"];
-
-// Response types
-export interface Run {
-    run_id: string;
-    status: RunStatus;
-    thread_id?: string;
-    agent_id: string;
-    bundle_id?: string;
-    agent_version_id?: string;
-    tenant_id: string;
-    workspace_id: string;
-    input?: unknown;
-    output?: unknown;
-    error?: unknown;
-    current_attempt_id?: string;
-    current_attempt_no?: number;
-    latest_seq?: number;
-    created_at: string;
-    started_at?: string;
-    completed_at?: string;
-    duration_ms?: number;
-    reused?: boolean;
-    // HITL (Human-in-the-Loop) fields
-    human_prompt?: string;
-    checkpoint_id?: string;
-    // Replay fields
-    replayed_from_run_id?: string;
-    replayed_from_checkpoint_id?: string;
-    replay_mode?: "best_effort" | "strict";
-}
-
-// Run status values
-export type RunStatus =
-    | "pending"
-    | "queued"
-    | "running"
-    | "completed"
-    | "failed"
-    | "cancelled"
-    | "waiting_for_human"
-    | "resumed";
-
-export interface CreateRunResponse {
-    run_id: string;
-    status: string;
-    reused?: boolean;
-}
-
-export type RunListResponse = PaginatedResponse<Run>;
-
-/** Wave 2.3: Seq-based polling response for execution events */
-export interface RunEventsPollResponse {
-    events: RunEventDto[];
-    latest_seq: number;
-    next_after_seq: number | null;
-    has_more: boolean;
-}
-
-/** Single event from seq-based polling */
-export interface RunEventDto {
-    id: string;
-    seq: number;
-    type: string;
-    timestamp: string;
-    attempt_id: string;
-    payload: Record<string, unknown> | null;
-    operation_id: string;
-    parent_operation_id?: string | null;
-    root_operation_id: string;
-}
-
-export interface RunInspectionResponse {
-    run: Record<string, unknown>;
-    replay: Record<string, unknown>;
-    failure: Record<string, unknown>;
-    attempts: Array<Record<string, unknown>>;
-    node_executions: Array<Record<string, unknown>>;
-    events: Array<Record<string, unknown>>;
-}
-
-export interface RunFailureRetentionItem {
-    failure_id: string;
-    failure_scope: string;
-    run_id: string;
-    attempt_id: string;
-    attempt_no: number;
-    agent_id?: string | null;
-    thread_id: string;
-    node_execution_id?: string | null;
-    operation_id?: string | null;
-    capability_ref?: string | null;
-    capability_version?: string | null;
-    execution_binding?: string | null;
-    source_kind: string;
-    ancestry_kind: string;
-    status: string;
-    error_code: string;
-    error_category: string;
-    is_retryable: boolean;
-    error_source: string;
-    provider_error_code?: string | null;
-    error_summary: string;
-    retried_from_node_execution_id?: string | null;
-    replayed_from_node_execution_id?: string | null;
-    can_retry: boolean;
-    retry_from_node_execution_id?: string | null;
-    can_replay: boolean;
-    replay_from_node_execution_id?: string | null;
-    failed_at: string;
-    created_at: string;
-}
-
-export interface RunFailureRetentionListResponse {
-    items: RunFailureRetentionItem[];
-    count: number;
-}
-
-export interface RunFailureRetentionDetailResponse {
-    failure: RunFailureRetentionItem;
-    payload?: unknown;
-}
-
-export interface RunObservabilitySummaryResponse {
-    workspace_id: string;
-    agent_id?: string | null;
-    from?: string | null;
-    to?: string | null;
-    runs_total: number;
-    runs_completed: number;
-    runs_failed: number;
-    node_executions_total: number;
-    node_executions_failed: number;
-    retry_count: number;
-    replay_count: number;
-    handoff_count: number;
-    avg_run_latency_ms: number;
-    p95_run_latency_ms: number;
-    avg_node_latency_ms: number;
-    failure_rate: number;
-    top_error_categories: Array<{
-        error_category: string;
-        count: number;
-    }>;
-}
-
-export interface RunObservabilityCapabilityListResponse {
-    items: Array<Record<string, unknown>>;
-    count: number;
-}
-
-export interface RunObservabilityBindingListResponse {
-    items: Array<Record<string, unknown>>;
-    count: number;
-}
-
-export class RunsModule {
-    constructor(private client: RawClient) { }
-
-    // ======================== CRUD ========================
-
-    /**
-     * Create a new run.
-     * @example
-     * ```ts
-     * const { data } = await client.runs.create({
-     *   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;
-        /** Optional bundle pinning (draft/published). When omitted, backend resolves live bundle. */
-        bundle_id?: string;
-        /** Idempotency key for safe retries. When set, duplicate requests with the same key return the original response. */
-        idempotency_key?: string;
-    }): Promise<APIResponse<CreateRunResponse>> {
-        // Send canonical X-Idempotency-Key header + body idempotency_key for backend contract parity.
-        const headers: Record<string, string> = {};
-        if (body.idempotency_key) {
-            headers["X-Idempotency-Key"] = body.idempotency_key;
-        }
-
-        return this.client.POST<CreateRunResponse>("/v1/api/runs", {
-            body,
-            headers,
-        });
-    }
-
-    /**
-     * Get a run by ID.
-     */
-    async get(runId: string): Promise<APIResponse<Run>> {
-        return this.client.GET<Run>("/v1/api/runs/{runId}", {
-            params: { path: { runId } },
-        });
-    }
-
-    async getInspection(runId: string): Promise<APIResponse<RunInspectionResponse>> {
-        return this.client.GET<RunInspectionResponse>("/v1/api/runs/{runId}/inspection", {
-            params: { path: { runId } },
-        });
-    }
-
-    async listFailures(params?: {
-        agent_id?: string;
-        capability_ref?: string;
-        error_category?: string;
-        retryable?: boolean;
-        from?: string;
-        to?: string;
-        limit?: number;
-        offset?: number;
-    }): Promise<APIResponse<RunFailureRetentionListResponse>> {
-        return this.client.GET<RunFailureRetentionListResponse>("/v1/api/runs/failures", {
-            params: { query: params },
-        });
-    }
-
-    async getFailure(failureId: string): Promise<APIResponse<RunFailureRetentionDetailResponse>> {
-        return this.client.GET<RunFailureRetentionDetailResponse>("/v1/api/runs/failures/{failureId}", {
-            params: { path: { failureId } },
-        });
-    }
-
-    /**
-     * List runs with optional filters.
-     */
-    async list(params?: PaginationParams & {
-        thread_id?: string;
-        agent_id?: string;
-        status?: string;
-    }): Promise<APIResponse<RunListResponse>> {
-        return this.client.GET<RunListResponse>("/v1/api/runs", {
-            params: { query: params },
-        });
-    }
-
-    /**
-     * 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 ========================
-
-    /**
-     * Wait for run completion synchronously.
-     */
-    async wait(body: {
-        agent_id: string;
-        thread?: { thread_id?: string } | { new_thread: true };
-        input?: unknown;
-        timeout_seconds?: number;
-    }): Promise<APIResponse<WaitRunResponse>> {
-        return this.client.POST<WaitRunResponse>("/v1/api/runs/wait", {
-            body,
-        });
-    }
-
-    /**
-     * Create batch runs.
-     */
-    async batch(body: {
-        agent_id: string;
-        inputs: Array<{ input: unknown; idempotency_key?: string }>;
-    }): Promise<APIResponse<BatchRunResponse>> {
-        return this.client.POST<BatchRunResponse>("/v1/api/runs/batch", {
-            body,
-        });
-    }
-
-    /**
-     * Cancel a running run.
-     */
-    async cancel(runId: string, reason?: string): Promise<APIResponse<CancelRunResponse>> {
-        return this.client.POST<CancelRunResponse>("/v1/api/runs/{runId}/cancel", {
-            params: { path: { runId } },
-            body: { reason },
-        });
-    }
-
-    async getObservabilitySummary(params?: {
-        agent_id?: string;
-        from?: string;
-        to?: string;
-    }): Promise<APIResponse<RunObservabilitySummaryResponse>> {
-        return this.client.GET<RunObservabilitySummaryResponse>("/v1/api/runs/observability/summary", {
-            params: { query: params },
-        });
-    }
-
-    async getObservabilityCapabilities(params?: {
-        agent_id?: string;
-        from?: string;
-        to?: string;
-        limit?: number;
-        offset?: number;
-    }): Promise<APIResponse<RunObservabilityCapabilityListResponse>> {
-        return this.client.GET<RunObservabilityCapabilityListResponse>("/v1/api/runs/observability/capabilities", {
-            params: { query: params },
-        });
-    }
-
-    async getObservabilityBindings(params?: {
-        agent_id?: string;
-        from?: string;
-        to?: string;
-        limit?: number;
-        offset?: number;
-    }): Promise<APIResponse<RunObservabilityBindingListResponse>> {
-        return this.client.GET<RunObservabilityBindingListResponse>("/v1/api/runs/observability/bindings", {
-            params: { query: params },
-        });
-    }
-
-    /**
-     * Resume a run waiting for human input (HITL).
-     * After the run reaches status 'waiting_for_human', use this to provide
-     * the human response and continue execution.
-     * 
-     * @param runId - The run ID to resume
-     * @param body - The human input to provide
-     * @returns Updated run (status will change to 'resumed' then 'queued')
-     * 
-     * @example
-     * ```ts
-     * // List runs waiting for human input
-     * const waiting = await client.runs.list({ status: 'waiting_for_human' })
-     * 
-     * // Get the prompt
-     * const run = await client.runs.get(runId)
-     * console.log(run.human_prompt)  // "Deseja continuar com a compra?"
-     * 
-     * // Respond
-     * await client.runs.resume(runId, { input: { answer: "sim" } })
-     * ```
-     */
-    async resume(runId: string, body: { input: unknown }): Promise<APIResponse<Run>> {
-        return this.client.POST<Run>("/v1/api/runs/{runId}/resume", {
-            params: { path: { runId } },
-            body,
-        });
-    }
-
-    /**
-     * Rerun from start (stateless).
-     */
-    async rerun(runId: string): Promise<APIResponse<CreateRunResponse>> {
-        return this.client.POST<CreateRunResponse>("/v1/api/runs/{runId}/rerun", {
-            params: { path: { runId } },
-        });
-    }
-
-    /**
-     * Replay from checkpoint (stateful).
-     * Creates a NEW run that starts from the specified checkpoint.
-     */
-    async replay(
-        runId: string,
-        checkpointId: string,
-        options?: {
-            mode?: "best_effort" | "strict";
-            reason?: string;
-        }
-    ): Promise<APIResponse<RunReplayResponse>> {
-        return this.client.POST<RunReplayResponse>("/v1/api/runs/{runId}/checkpoints/{checkpointId}/replay", {
-            params: { path: { runId, checkpointId } },
-            body: {
-                mode: options?.mode,
-                reason: options?.reason
-            },
-        });
-    }
-
-    // ======================== Events ========================
-
-    /**
-     * Get canonical run events from SSOT ledger (polling by seq).
-     */
-    async getEvents(runId: string, params: {
-        attemptId: string;
-        afterSeq?: number;
-        limit?: number;
-    }): Promise<APIResponse<RunEventsPollResponse>> {
-        return this.client.GET<RunEventsPollResponse>("/v1/api/runs/{runId}/events", {
-            params: {
-                path: { runId },
-                query: {
-                    attemptId: params.attemptId,
-                    afterSeq: params.afterSeq ?? 0,
-                    limit: params.limit ?? 100,
-                },
-            },
-        });
-    }
-
-    /** Alias: runs.events() -> runs.getEvents() */
-    events = (runId: string, params: { attemptId: string; afterSeq?: number; limit?: number }) =>
-        this.getEvents(runId, params);
-
-    /**
-     * Wave 2.3: Seq-based event polling for execution trace.
-     * Use this for incremental polling with reconnection support.
-     * 
-     * @param runId - Run ID to poll events for
-     * @param params - Polling options
-     * @returns Events with seq cursors for pagination
-     * 
-     * @example
-     * ```ts
-     * let afterSeq = 0;
-     * const attemptId = "attempt-uuid";
-     * while (run.status === 'running') {
-     *   const { data } = await client.runs.pollEvents(runId, { attemptId, afterSeq });
-     *   for (const event of data.events) {
-     *     console.log(event.type, event.payload);
-     *   }
-     *   afterSeq = data.next_after_seq;
-     *   await sleep(1000);
-     * }
-     * ```
-     */
-    async pollEvents(runId: string, params: {
-        attemptId: string;
-        afterSeq?: number;
-        limit?: number;
-    }): Promise<APIResponse<RunEventsPollResponse>> {
-        return this.client.GET<RunEventsPollResponse>("/v1/api/runs/{runId}/events", {
-            params: {
-                path: { runId },
-                query: {
-                    attemptId: params.attemptId,
-                    afterSeq: params.afterSeq ?? 0,
-                    limit: params.limit ?? 100
-                }
-            },
-        });
-    }
-
-    // ======================== Checkpoints ========================
-
-    /**
-     * Get checkpoints for a run.
-     */
-    async getCheckpoints(runId: string): Promise<APIResponse<CheckpointIndexResponse>> {
-        return this.client.GET<CheckpointIndexResponse>("/v1/api/runs/{runId}/checkpoints/index", {
-            params: { path: { runId } },
-        });
-    }
-
-    /** Alias: runs.checkpoints() -> runs.getCheckpoints() */
-    checkpoints = (runId: string) => this.getCheckpoints(runId);
-
-    // ======================== FOLLOW (SSOT SSE) ========================
-
-    /**
-     * Follow a run attempt's canonical event stream with automatic reconnection.
-     *
-     * SSOT contract:
-     * - Stream is keyed by (run_id, attempt_id, seq)
-     * - Resume is driven by `afterSeq` (monotonic)
-     * - No implicit attempt inference
-     * 
-     * @example
-     * ```ts
-     * for await (const event of client.runs.follow(runId, attemptId)) {
-     *     if (event.type === "run_event") {
-     *         console.log(event.payload);
-     *     } else if (event.type === "close") {
-     *         console.log("Run completed");
-     *     }
-     * }
-     * ```
-     */
-    async *follow(runId: string, attemptId: string, options?: FollowOptions): AsyncGenerator<FollowEvent, void, unknown> {
-        if (!attemptId) {
-            throw new Error("attemptId is required for run event streaming");
-        }
-
-        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}/events/stream", {
-                    params: {
-                        path: { runId },
-                        query: {
-                            attemptId,
-                            afterSeq: nextSeq > 0 ? nextSeq : 0,
-                        },
-                    },
-                    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;
-                    }
-
-                    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;
-
-                    if (event.type === "run_event" && isTerminalRunEvent(event)) {
-                        receivedTerminal = true;
-                        yield {
-                            type: "close",
-                            seq: event.seq,
-                            timestamp: event.timestamp,
-                            payload: { terminal: true },
-                        };
-                        return;
-                    }
-                }
-
-                // 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;
-                }
-            }
-        }
-    }
-
-    /**
-     * Create run and follow canonical SSOT stream for the current attempt.
-     */
-    async *createAndStream(
-        body: {
-            agent_id: string;
-            thread?: { thread_id?: string } | { new_thread: true };
-            input?: unknown;
-            /** Idempotency key for safe retries. */
-            idempotency_key?: string;
-        },
-        options?: FollowOptions
-    ): AsyncGenerator<FollowEvent, void, unknown> {
-        const { data, error } = await this.create(body);
-        if (error || !data) {
-            throw new Error(`Failed to create run: ${JSON.stringify(error)}`);
-        }
-
-        const runId = data.run_id;
-        const runResponse = await this.get(runId);
-        if (runResponse.error || !runResponse.data?.current_attempt_id) {
-            throw new Error("Run created without current_attempt_id; cannot stream SSOT events");
-        }
-
-        yield* this.follow(runId, runResponse.data.current_attempt_id, options);
-    }
-
-    /**
-     * Wait for a specific event that matches a predicate.
-     * 
-     * @example
-     * ```ts
-     * // Wait for run completion
-     * const event = await client.runs.waitFor(runId, attemptId, (e) => e.type === "close", {
-     *     timeoutMs: 60000
-     * });
-     * 
-     * // Wait for specific node execution
-     * const nodeEvent = await client.runs.waitFor(runId, attemptId, (e) => 
-     *     e.type === "run_event" && e.payload?.node === "my_node"
-     * );
-     * ```
-     */
-    async waitFor(
-        runId: string,
-        attemptId: 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, attemptId, {
-                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;
-    operation_id?: string;
-    parent_operation_id?: string | null;
-    root_operation_id?: string;
-    /** For run_event: the node that emitted this event */
-    node?: string;
-}
-
-/** Narrow raw SSE event to FollowEvent */
-export 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;
-
-    // Canonical payload from backend SSE is RunEventDto:
-    // { id, seq, type, timestamp, attempt_id, payload }
-    if (eventType === "run_event" && data) {
-        const seq = typeof data.seq === "number" ? data.seq : (raw.id ? parseInt(raw.id, 10) : -1);
-        const timestamp = typeof data.timestamp === "string" ? data.timestamp : new Date().toISOString();
-        const innerPayload = (typeof data.payload === "object" && data.payload !== null)
-            ? (data.payload as Record<string, unknown>)
-            : null;
-        const operationId = typeof data.operation_id === "string" ? data.operation_id : undefined;
-        const parentOperationId = typeof data.parent_operation_id === "string"
-            ? data.parent_operation_id
-            : data.parent_operation_id === null
-                ? null
-                : undefined;
-        const rootOperationId = typeof data.root_operation_id === "string" ? data.root_operation_id : undefined;
-
-        return {
-            type: "run_event",
-            seq,
-            timestamp,
-            payload: {
-                ...(innerPayload ?? {}),
-                type: typeof data.type === "string" ? data.type : "UNKNOWN",
-                attempt_id: typeof data.attempt_id === "string" ? data.attempt_id : undefined,
-                operation_id: operationId,
-                parent_operation_id: parentOperationId,
-                root_operation_id: rootOperationId,
-            },
-            operation_id: operationId,
-            parent_operation_id: parentOperationId,
-            root_operation_id: rootOperationId,
-            node: typeof innerPayload?.node === "string" ? innerPayload.node : undefined,
-        };
-    }
-
-    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,
-    };
-}
-
-function isTerminalRunEvent(event: FollowEvent): boolean {
-    const type = typeof event.payload?.type === "string"
-        ? event.payload.type.toUpperCase()
-        : "";
-
-    return type === "RUN_FINISHED" || type === "RUN_FAILED" || type === "RUN_CANCELLED";
-}
-
-/** 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));
-}