retrace-sdk 0.1.4 → 0.1.6

package/dist/sdk.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk.test.js

@@ -0,0 +1,132 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { configure, getConfig } from "./config.js";
+// Reset config between tests
+beforeEach(() => {
+    configure({ apiKey: "", baseUrl: "http://localhost:3001", enabled: true, wsUrl: "" });
+});
+describe("Config", () => {
+    it("has sensible defaults", () => {
+        const c = getConfig();
+        expect(c.baseUrl).toBe("http://localhost:3001");
+        expect(c.enabled).toBe(true);
+    });
+    it("configures custom values", () => {
+        configure({ apiKey: "rt_live_test", baseUrl: "https://api.example.com" });
+        const c = getConfig();
+        expect(c.apiKey).toBe("rt_live_test");
+        expect(c.baseUrl).toBe("https://api.example.com");
+        expect(c.wsUrl).toBe("wss://api.example.com");
+    });
+    it("auto-derives wsUrl from baseUrl", () => {
+        configure({ baseUrl: "https://custom.io" });
+        expect(getConfig().wsUrl).toBe("wss://custom.io");
+        configure({ baseUrl: "http://localhost:3001" });
+        expect(getConfig().wsUrl).toBe("ws://localhost:3001");
+    });
+    it("warns on invalid API key prefix", () => {
+        const spy = vi.spyOn(console, "warn").mockImplementation(() => { });
+        configure({ apiKey: "invalid_key" });
+        expect(spy).toHaveBeenCalledWith(expect.stringContaining("rt_live_"));
+        spy.mockRestore();
+    });
+    it("does not warn on valid API key", () => {
+        const spy = vi.spyOn(console, "warn").mockImplementation(() => { });
+        configure({ apiKey: "rt_live_valid123" });
+        expect(spy).not.toHaveBeenCalled();
+        spy.mockRestore();
+    });
+});
+describe("Trace model", () => {
+    it("SpanBuilder creates valid span data", async () => {
+        const { SpanBuilder, SpanType } = await import("./trace.js");
+        const sb = new SpanBuilder("test-span", SpanType.LLM_CALL).start();
+        sb.setModel("gpt-4o");
+        sb.setInput({ prompt: "hi" });
+        const data = sb.end("hello");
+        expect(data.name).toBe("test-span");
+        expect(data.span_type).toBe("llm_call");
+        expect(data.model).toBe("gpt-4o");
+        expect(data.output).toBe("hello");
+        expect(data.id).toHaveLength(36);
+        expect(data.started_at).toBeDefined();
+        expect(data.ended_at).toBeDefined();
+    });
+    it("TraceBuilder creates valid trace data", async () => {
+        const { TraceBuilder, TraceStatus } = await import("./trace.js");
+        const tb = new TraceBuilder();
+        tb.start("my-trace", { prompt: "test" });
+        const data = tb.end("result", TraceStatus.COMPLETED);
+        expect(data.name).toBe("my-trace");
+        expect(data.status).toBe("completed");
+        expect(data.output).toBe("result");
+        expect(data.id).toHaveLength(36);
+    });
+    it("SpanType enum values", async () => {
+        const { SpanType } = await import("./trace.js");
+        expect(SpanType.LLM_CALL).toBe("llm_call");
+        expect(SpanType.TOOL_CALL).toBe("tool_call");
+        expect(SpanType.ERROR).toBe("error");
+        expect(SpanType.FORK_POINT).toBe("fork_point");
+    });
+});
+describe("Recorder", () => {
+    it("trace() wraps sync function", async () => {
+        configure({ apiKey: "rt_live_t", baseUrl: "http://x:1", enabled: true });
+        const { trace } = await import("./recorder.js");
+        const fn = trace((x) => `result:${x}`, { name: "sync-fn" });
+        expect(fn("hi")).toBe("result:hi");
+    });
+    it("trace() wraps async function", async () => {
+        configure({ apiKey: "rt_live_t", baseUrl: "http://x:1", enabled: true });
+        const { trace } = await import("./recorder.js");
+        const fn = trace(async (x) => `async:${x}`, { name: "async-fn" });
+        const result = await fn("hi");
+        expect(result).toBe("async:hi");
+    });
+    it("trace() propagates exceptions", async () => {
+        configure({ apiKey: "rt_live_t", baseUrl: "http://x:1", enabled: true });
+        const { trace } = await import("./recorder.js");
+        const fn = trace(() => { throw new Error("boom"); }, { name: "err-fn" });
+        expect(() => fn()).toThrow("boom");
+    });
+    it("disabled SDK is no-op", async () => {
+        configure({ apiKey: "rt_live_t", enabled: false });
+        const { trace } = await import("./recorder.js");
+        const fn = trace((x) => `r:${x}`, { name: "off" });
+        expect(fn("hi")).toBe("r:hi");
+    });
+});
+describe("Transport", () => {
+    it("HTTPTransport accumulates and flushes", async () => {
+        configure({ apiKey: "rt_live_t", baseUrl: "http://x:1" });
+        const { HTTPTransport } = await import("./transport.js");
+        const http = new HTTPTransport();
+        const mockFetch = vi.fn().mockResolvedValue({ ok: true });
+        vi.stubGlobal("fetch", mockFetch);
+        http.send("trace_started", { id: "abc", name: "t", status: "running", started_at: "2026-01-01T00:00:00Z", total_tokens: 0, total_cost: 0, total_duration_ms: 0 });
+        http.send("span_started", { id: "s1", trace_id: "abc", span_type: "llm_call", name: "s", started_at: "2026-01-01T00:00:00Z" });
+        http.send("span_ended", { id: "s1", ended_at: "2026-01-01T00:00:01Z", output: "hi" });
+        http.send("trace_ended", { id: "abc", ended_at: "2026-01-01T00:00:02Z", status: "completed" });
+        expect(mockFetch).toHaveBeenCalled();
+        const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+        expect(body.id).toBe("abc");
+        expect(body.spans).toHaveLength(1);
+        expect(body.spans[0].output).toBe("hi");
+        vi.unstubAllGlobals();
+    });
+    it("createTransport returns correct type", async () => {
+        const { createTransport, HTTPTransport } = await import("./transport.js");
+        expect(createTransport("http")).toBeInstanceOf(HTTPTransport);
+    });
+});
+describe("README examples", () => {
+    it("TypeScript README example works", async () => {
+        configure({ apiKey: "rt_live_test", enabled: false });
+        const { trace } = await import("./recorder.js");
+        const runAgent = trace(async (prompt) => {
+            return `Response to: ${prompt}`;
+        }, { name: "my-agent" });
+        const result = await runAgent("What is quantum computing?");
+        expect(result).toContain("quantum");
+    });
+});

package/dist/transport.d.ts

@@ -5,8 +5,10 @@ export interface Transport {
 export declare class WSTransport implements Transport {
     private ws;
     private connected;
+    private closed;
     private backoff;
     private queue;
+    get isConnected(): boolean;
     connect(): void;
     private reconnect;
     private flushQueue;

package/dist/transport.js

@@ -3,9 +3,13 @@ import { getConfig } from "./config.js";
 export class WSTransport {
     ws = null;
     connected = false;
+    closed = false;
     backoff = 1000;
     queue = [];
+    get isConnected() { return this.connected; }
     connect() {
+        if (this.closed)
+            return;
         const cfg = getConfig();
         const url = `${cfg.wsUrl}/ws/v1/stream`;
         this.ws = new WebSocket(url);
@@ -26,15 +30,17 @@ export class WSTransport {
         this.ws.on("close", () => {
             this.connected = false;
             this.ws = null;
-            setTimeout(() => this.reconnect(), this.backoff);
-            this.backoff = Math.min(this.backoff * 2, 30000);
+            if (!this.closed) {
+                setTimeout(() => this.reconnect(), this.backoff);
+                this.backoff = Math.min(this.backoff * 2, 30000);
+            }
         });
         this.ws.on("error", () => {
             this.ws?.close();
         });
     }
     reconnect() {
-        if (!this.connected && !this.ws)
+        if (!this.closed && !this.connected && !this.ws)
             this.connect();
     }
     flushQueue() {
@@ -49,11 +55,12 @@ export class WSTransport {
         }
         else {
             this.queue.push(msg);
-            if (!this.ws)
+            if (!this.ws && !this.closed)
                 this.connect();
         }
     }
     close() {
+        this.closed = true;
         if (this.ws) {
             this.ws.close();
             this.ws = null;
@@ -114,11 +121,61 @@ export function createTransport(mode = "auto") {
         return new HTTPTransport();
     if (mode === "ws")
         return new WSTransport();
-    // Auto: try WS
-    try {
-        return new WSTransport();
-    }
-    catch {
-        return new HTTPTransport();
-    }
+    // Auto: start with WS, fall back to HTTP if connection fails within timeout
+    const ws = new WSTransport();
+    const http = new HTTPTransport();
+    let useWs = true;
+    let decided = false;
+    const buffer = [];
+    const fallbackTimer = setTimeout(() => {
+        if (!decided && !ws.isConnected) {
+            decided = true;
+            useWs = false;
+            ws.close();
+            for (const item of buffer.splice(0))
+                http.send(item.eventType, item.data);
+        }
+    }, 5000);
+    ws.connect();
+    const originalSend = ws.send.bind(ws);
+    const checkConnected = () => {
+        if (!decided && ws.isConnected) {
+            decided = true;
+            clearTimeout(fallbackTimer);
+            for (const item of buffer.splice(0))
+                originalSend(item.eventType, item.data);
+        }
+    };
+    return {
+        send(eventType, data) {
+            checkConnected();
+            if (decided) {
+                if (useWs)
+                    originalSend(eventType, data);
+                else
+                    http.send(eventType, data);
+            }
+            else {
+                buffer.push({ eventType, data });
+            }
+        },
+        close() {
+            clearTimeout(fallbackTimer);
+            if (!decided) {
+                // WS not yet connected — force HTTP fallback to avoid data loss
+                decided = true;
+                useWs = false;
+                ws.close();
+                for (const item of buffer.splice(0))
+                    http.send(item.eventType, item.data);
+                http.close();
+            }
+            else if (useWs) {
+                ws.close();
+            }
+            else {
+                http.close();
+            }
+        },
+    };
 }

package/dist/transport.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/transport.test.js

@@ -0,0 +1,67 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { configure } from "./config.js";
+// Mock WebSocket to never connect (simulates unreachable WS endpoint)
+const mockWsInstances = [];
+vi.mock("ws", () => {
+    const MockWebSocket = function () {
+        this.readyState = 0;
+        this._listeners = {};
+        this.on = (event, cb) => { (this._listeners[event] ??= []).push(cb); return this; };
+        this.send = vi.fn();
+        this.close = vi.fn(() => {
+            this.readyState = 3;
+            for (const cb of (this._listeners["close"] ?? []))
+                cb();
+        });
+        mockWsInstances.push(this);
+    };
+    MockWebSocket.OPEN = 1;
+    return { default: MockWebSocket };
+});
+beforeEach(() => {
+    configure({ apiKey: "rt_live_test", baseUrl: "http://localhost:3001", enabled: true });
+    mockWsInstances.length = 0;
+});
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+describe("Auto transport fallback on early close()", () => {
+    it("flushes to HTTP when close() is called before WS connects", async () => {
+        const mockFetch = vi.fn().mockResolvedValue({ ok: true });
+        vi.stubGlobal("fetch", mockFetch);
+        const { createTransport } = await import("./transport.js");
+        const transport = createTransport("auto");
+        // Send trace events immediately (before WS could connect)
+        transport.send("trace_started", { id: "t1", name: "fast-trace", status: "running", started_at: "2026-01-01T00:00:00Z", total_tokens: 0, total_cost: 0, total_duration_ms: 0 });
+        transport.send("span_started", { id: "s1", trace_id: "t1", span_type: "llm_call", name: "call", started_at: "2026-01-01T00:00:00Z" });
+        transport.send("span_ended", { id: "s1", ended_at: "2026-01-01T00:00:01Z", output: "response" });
+        transport.send("trace_ended", { id: "t1", ended_at: "2026-01-01T00:00:01Z", status: "completed" });
+        // Close immediately — WS has NOT connected yet
+        transport.close();
+        // Should have fallen back to HTTP and flushed
+        expect(mockFetch).toHaveBeenCalledTimes(1);
+        const [url, opts] = mockFetch.mock.calls[0];
+        expect(url).toBe("http://localhost:3001/api/v1/traces");
+        const body = JSON.parse(opts.body);
+        expect(body.id).toBe("t1");
+        expect(body.name).toBe("fast-trace");
+        expect(body.spans).toHaveLength(1);
+        expect(body.spans[0].output).toBe("response");
+    });
+    it("does NOT reconnect after intentional close()", async () => {
+        vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: true }));
+        const { WSTransport } = await import("./transport.js");
+        const ws = new WSTransport();
+        ws.connect();
+        // Should have created a WS instance
+        expect(mockWsInstances.length).toBeGreaterThan(0);
+        const instanceCount = mockWsInstances.length;
+        // Close intentionally
+        ws.close();
+        // Trigger the "close" event that was registered — already fired by our mock's close()
+        // Wait a tick for any setTimeout reconnect to fire
+        await new Promise(r => setTimeout(r, 1100));
+        // Should NOT have created new WS instances (no reconnect)
+        expect(mockWsInstances.length).toBe(instanceCount);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retrace-sdk",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "The execution replay engine for AI agents. Record, replay, fork, and share agent executions.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,8 +29,9 @@
     }
   },
   "devDependencies": {
-    "typescript": "6.0.3",
+    "@google/genai": "^1.52.0",
     "@types/node": "22.15.3",
-    "@types/ws": "8.18.1"
+    "@types/ws": "8.18.1",
+    "typescript": "6.0.3"
   }
 }

package/src/sdk.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { configure, getConfig } from "./config.js";
+
+// Reset config between tests
+beforeEach(() => {
+  configure({ apiKey: "", baseUrl: "http://localhost:3001", enabled: true, wsUrl: "" });
+});
+
+describe("Config", () => {
+  it("has sensible defaults", () => {
+    const c = getConfig();
+    expect(c.baseUrl).toBe("http://localhost:3001");
+    expect(c.enabled).toBe(true);
+  });
+
+  it("configures custom values", () => {
+    configure({ apiKey: "rt_live_test", baseUrl: "https://api.example.com" });
+    const c = getConfig();
+    expect(c.apiKey).toBe("rt_live_test");
+    expect(c.baseUrl).toBe("https://api.example.com");
+    expect(c.wsUrl).toBe("wss://api.example.com");
+  });
+
+  it("auto-derives wsUrl from baseUrl", () => {
+    configure({ baseUrl: "https://custom.io" });
+    expect(getConfig().wsUrl).toBe("wss://custom.io");
+    configure({ baseUrl: "http://localhost:3001" });
+    expect(getConfig().wsUrl).toBe("ws://localhost:3001");
+  });
+
+  it("warns on invalid API key prefix", () => {
+    const spy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    configure({ apiKey: "invalid_key" });
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining("rt_live_"));
+    spy.mockRestore();
+  });
+
+  it("does not warn on valid API key", () => {
+    const spy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    configure({ apiKey: "rt_live_valid123" });
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+describe("Trace model", () => {
+  it("SpanBuilder creates valid span data", async () => {
+    const { SpanBuilder, SpanType } = await import("./trace.js");
+    const sb = new SpanBuilder("test-span", SpanType.LLM_CALL).start();
+    sb.setModel("gpt-4o");
+    sb.setInput({ prompt: "hi" });
+    const data = sb.end("hello");
+    expect(data.name).toBe("test-span");
+    expect(data.span_type).toBe("llm_call");
+    expect(data.model).toBe("gpt-4o");
+    expect(data.output).toBe("hello");
+    expect(data.id).toHaveLength(36);
+    expect(data.started_at).toBeDefined();
+    expect(data.ended_at).toBeDefined();
+  });
+
+  it("TraceBuilder creates valid trace data", async () => {
+    const { TraceBuilder, TraceStatus } = await import("./trace.js");
+    const tb = new TraceBuilder();
+    tb.start("my-trace", { prompt: "test" });
+    const data = tb.end("result", TraceStatus.COMPLETED);
+    expect(data.name).toBe("my-trace");
+    expect(data.status).toBe("completed");
+    expect(data.output).toBe("result");
+    expect(data.id).toHaveLength(36);
+  });
+
+  it("SpanType enum values", async () => {
+    const { SpanType } = await import("./trace.js");
+    expect(SpanType.LLM_CALL).toBe("llm_call");
+    expect(SpanType.TOOL_CALL).toBe("tool_call");
+    expect(SpanType.ERROR).toBe("error");
+    expect(SpanType.FORK_POINT).toBe("fork_point");
+  });
+});
+
+describe("Recorder", () => {
+  it("trace() wraps sync function", async () => {
+    configure({ apiKey: "rt_live_t", baseUrl: "http://x:1", enabled: true });
+    const { trace } = await import("./recorder.js");
+    const fn = trace((x: unknown) => `result:${x}`, { name: "sync-fn" });
+    expect(fn("hi")).toBe("result:hi");
+  });
+
+  it("trace() wraps async function", async () => {
+    configure({ apiKey: "rt_live_t", baseUrl: "http://x:1", enabled: true });
+    const { trace } = await import("./recorder.js");
+    const fn = trace(async (x: unknown) => `async:${x}`, { name: "async-fn" });
+    const result = await fn("hi");
+    expect(result).toBe("async:hi");
+  });
+
+  it("trace() propagates exceptions", async () => {
+    configure({ apiKey: "rt_live_t", baseUrl: "http://x:1", enabled: true });
+    const { trace } = await import("./recorder.js");
+    const fn = trace(() => { throw new Error("boom"); }, { name: "err-fn" });
+    expect(() => fn()).toThrow("boom");
+  });
+
+  it("disabled SDK is no-op", async () => {
+    configure({ apiKey: "rt_live_t", enabled: false });
+    const { trace } = await import("./recorder.js");
+    const fn = trace((x: unknown) => `r:${x}`, { name: "off" });
+    expect(fn("hi")).toBe("r:hi");
+  });
+});
+
+describe("Transport", () => {
+  it("HTTPTransport accumulates and flushes", async () => {
+    configure({ apiKey: "rt_live_t", baseUrl: "http://x:1" });
+    const { HTTPTransport } = await import("./transport.js");
+    const http = new HTTPTransport();
+
+    const mockFetch = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal("fetch", mockFetch);
+
+    http.send("trace_started", { id: "abc", name: "t", status: "running", started_at: "2026-01-01T00:00:00Z", total_tokens: 0, total_cost: 0, total_duration_ms: 0 });
+    http.send("span_started", { id: "s1", trace_id: "abc", span_type: "llm_call", name: "s", started_at: "2026-01-01T00:00:00Z" });
+    http.send("span_ended", { id: "s1", ended_at: "2026-01-01T00:00:01Z", output: "hi" });
+    http.send("trace_ended", { id: "abc", ended_at: "2026-01-01T00:00:02Z", status: "completed" });
+
+    expect(mockFetch).toHaveBeenCalled();
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.id).toBe("abc");
+    expect(body.spans).toHaveLength(1);
+    expect(body.spans[0].output).toBe("hi");
+
+    vi.unstubAllGlobals();
+  });
+
+  it("createTransport returns correct type", async () => {
+    const { createTransport, HTTPTransport } = await import("./transport.js");
+    expect(createTransport("http")).toBeInstanceOf(HTTPTransport);
+  });
+});
+
+describe("README examples", () => {
+  it("TypeScript README example works", async () => {
+    configure({ apiKey: "rt_live_test", enabled: false });
+    const { trace } = await import("./recorder.js");
+    const runAgent = trace(async (prompt: unknown) => {
+      return `Response to: ${prompt}`;
+    }, { name: "my-agent" });
+    const result = await runAgent("What is quantum computing?");
+    expect(result).toContain("quantum");
+  });
+});

package/src/transport.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { configure } from "./config.js";
+
+// Mock WebSocket to never connect (simulates unreachable WS endpoint)
+const mockWsInstances: Array<Record<string, unknown>> = [];
+vi.mock("ws", () => {
+  const MockWebSocket = function (this: Record<string, unknown>) {
+    this.readyState = 0;
+    this._listeners = {} as Record<string, Array<() => void>>;
+    this.on = (event: string, cb: () => void) => { ((this._listeners as Record<string, Array<() => void>>)[event] ??= []).push(cb); return this; };
+    this.send = vi.fn();
+    this.close = vi.fn(() => {
+      this.readyState = 3;
+      for (const cb of ((this._listeners as Record<string, Array<() => void>>)["close"] ?? [])) cb();
+    });
+    mockWsInstances.push(this);
+  } as unknown as { new(): Record<string, unknown>; OPEN: number };
+  MockWebSocket.OPEN = 1;
+  return { default: MockWebSocket };
+});
+
+beforeEach(() => {
+  configure({ apiKey: "rt_live_test", baseUrl: "http://localhost:3001", enabled: true });
+  mockWsInstances.length = 0;
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("Auto transport fallback on early close()", () => {
+  it("flushes to HTTP when close() is called before WS connects", async () => {
+    const mockFetch = vi.fn().mockResolvedValue({ ok: true });
+    vi.stubGlobal("fetch", mockFetch);
+
+    const { createTransport } = await import("./transport.js");
+    const transport = createTransport("auto");
+
+    // Send trace events immediately (before WS could connect)
+    transport.send("trace_started", { id: "t1", name: "fast-trace", status: "running", started_at: "2026-01-01T00:00:00Z", total_tokens: 0, total_cost: 0, total_duration_ms: 0 });
+    transport.send("span_started", { id: "s1", trace_id: "t1", span_type: "llm_call", name: "call", started_at: "2026-01-01T00:00:00Z" });
+    transport.send("span_ended", { id: "s1", ended_at: "2026-01-01T00:00:01Z", output: "response" });
+    transport.send("trace_ended", { id: "t1", ended_at: "2026-01-01T00:00:01Z", status: "completed" });
+
+    // Close immediately — WS has NOT connected yet
+    transport.close();
+
+    // Should have fallen back to HTTP and flushed
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    const [url, opts] = mockFetch.mock.calls[0];
+    expect(url).toBe("http://localhost:3001/api/v1/traces");
+    const body = JSON.parse(opts.body);
+    expect(body.id).toBe("t1");
+    expect(body.name).toBe("fast-trace");
+    expect(body.spans).toHaveLength(1);
+    expect(body.spans[0].output).toBe("response");
+  });
+
+  it("does NOT reconnect after intentional close()", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: true }));
+
+    const { WSTransport } = await import("./transport.js");
+    const ws = new WSTransport();
+    ws.connect();
+
+    // Should have created a WS instance
+    expect(mockWsInstances.length).toBeGreaterThan(0);
+    const instanceCount = mockWsInstances.length;
+
+    // Close intentionally
+    ws.close();
+
+    // Trigger the "close" event that was registered — already fired by our mock's close()
+    // Wait a tick for any setTimeout reconnect to fire
+    await new Promise(r => setTimeout(r, 1100));
+
+    // Should NOT have created new WS instances (no reconnect)
+    expect(mockWsInstances.length).toBe(instanceCount);
+  });
+});

package/src/transport.ts

@@ -9,10 +9,14 @@ export interface Transport {
 export class WSTransport implements Transport {
   private ws: WebSocket | null = null;
   private connected = false;
+  private closed = false;
   private backoff = 1000;
   private queue: string[] = [];
 
+  get isConnected() { return this.connected; }
+
   connect() {
+    if (this.closed) return;
     const cfg = getConfig();
     const url = `${cfg.wsUrl}/ws/v1/stream`;
     this.ws = new WebSocket(url);
@@ -35,8 +39,10 @@ export class WSTransport implements Transport {
     this.ws.on("close", () => {
       this.connected = false;
       this.ws = null;
-      setTimeout(() => this.reconnect(), this.backoff);
-      this.backoff = Math.min(this.backoff * 2, 30000);
+      if (!this.closed) {
+        setTimeout(() => this.reconnect(), this.backoff);
+        this.backoff = Math.min(this.backoff * 2, 30000);
+      }
     });
 
     this.ws.on("error", () => {
@@ -45,7 +51,7 @@ export class WSTransport implements Transport {
   }
 
   private reconnect() {
-    if (!this.connected && !this.ws) this.connect();
+    if (!this.closed && !this.connected && !this.ws) this.connect();
   }
 
   private flushQueue() {
@@ -60,11 +66,12 @@ export class WSTransport implements Transport {
       this.ws.send(msg);
     } else {
       this.queue.push(msg);
-      if (!this.ws) this.connect();
+      if (!this.ws && !this.closed) this.connect();
     }
   }
 
   close() {
+    this.closed = true;
     if (this.ws) {
       this.ws.close();
       this.ws = null;
@@ -124,10 +131,58 @@ export class HTTPTransport implements Transport {
 export function createTransport(mode: "ws" | "http" | "auto" = "auto"): Transport {
   if (mode === "http") return new HTTPTransport();
   if (mode === "ws") return new WSTransport();
-  // Auto: try WS
-  try {
-    return new WSTransport();
-  } catch {
-    return new HTTPTransport();
-  }
+
+  // Auto: start with WS, fall back to HTTP if connection fails within timeout
+  const ws = new WSTransport();
+  const http = new HTTPTransport();
+  let useWs = true;
+  let decided = false;
+  const buffer: Array<{ eventType: string; data: Record<string, unknown> }> = [];
+
+  const fallbackTimer = setTimeout(() => {
+    if (!decided && !ws.isConnected) {
+      decided = true;
+      useWs = false;
+      ws.close();
+      for (const item of buffer.splice(0)) http.send(item.eventType, item.data);
+    }
+  }, 5000);
+
+  ws.connect();
+
+  const originalSend = ws.send.bind(ws);
+  const checkConnected = () => {
+    if (!decided && ws.isConnected) {
+      decided = true;
+      clearTimeout(fallbackTimer);
+      for (const item of buffer.splice(0)) originalSend(item.eventType, item.data);
+    }
+  };
+
+  return {
+    send(eventType: string, data: Record<string, unknown>) {
+      checkConnected();
+      if (decided) {
+        if (useWs) originalSend(eventType, data);
+        else http.send(eventType, data);
+      } else {
+        buffer.push({ eventType, data });
+      }
+    },
+    close() {
+      clearTimeout(fallbackTimer);
+      if (!decided) {
+        // WS not yet connected — force HTTP fallback to avoid data loss
+        decided = true;
+        useWs = false;
+        ws.close();
+        for (const item of buffer.splice(0)) http.send(item.eventType, item.data);
+        http.close();
+      } else if (useWs) {
+        ws.close();
+      } else {
+        http.close();
+      }
+    },
+  };
 }