@cf-vibesdk/sdk 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,140 @@
+# @cf-vibesdk/sdk
+
+Client SDK for the VibeSDK platform.
+
+## Install
+
+```bash
+npm install @cf-vibesdk/sdk
+```
+
+## Quickstart (Bun)
+
+```ts
+import { PhasicClient } from '@cf-vibesdk/sdk';
+
+const client = new PhasicClient({
+  baseUrl: 'http://localhost:5173',
+  apiKey: process.env.VIBESDK_API_KEY!,
+});
+
+const session = await client.build('Build a simple hello world page.', {
+  projectType: 'app',
+  autoGenerate: true,
+});
+
+// High-level lifecycle waits
+await session.wait.generationStarted();
+await session.wait.deployable();
+
+// Preview deployment (command + awaitable)
+const previewWait = session.wait.previewDeployed();
+session.deployPreview();
+const deployed = await previewWait;
+
+console.log('Preview URL:', deployed.previewURL);
+
+// Workspace is always kept in sync from agent state + WS events
+console.log(session.files.listPaths());
+console.log(session.files.read('README.md'));
+
+session.close();
+```
+
+## Quickstart (Node)
+
+Node requires a WebSocket factory (the browser `WebSocket` global is not available):
+
+```ts
+import { PhasicClient } from '@cf-vibesdk/sdk';
+import { createNodeWebSocketFactory } from '@cf-vibesdk/sdk/node';
+
+const client = new PhasicClient({
+  baseUrl: 'http://localhost:5173',
+  apiKey: process.env.VIBESDK_API_KEY!,
+  webSocketFactory: createNodeWebSocketFactory(),
+});
+
+const session = await client.build('Build a simple hello world page.', {
+  projectType: 'app',
+  autoGenerate: true,
+});
+
+await session.wait.generationStarted();
+await session.wait.deployable();
+session.close();
+```
+
+## Authentication
+
+Use either:
+
+- `apiKey`: a VibeSDK API key (recommended for CLIs and automation)
+- `token`: an already-minted JWT access token
+
+When `apiKey` is provided, the SDK exchanges it for a short-lived access token and caches it.
+
+## Workspace (no platform file APIs)
+
+The SDK reconstructs and maintains a local view of the codebase using:
+
+- `agent_connected.state.generatedFilesMap`
+- `cf_agent_state.state.generatedFilesMap`
+- incremental `file_*` messages
+
+APIs:
+
+- `session.files.listPaths()`
+- `session.files.read(path)`
+- `session.files.snapshot()`
+- `session.files.tree()`
+
+## Waiting primitives
+
+Use high-level waits instead of depending on agent-internal message ordering:
+
+- `session.wait.generationStarted()`
+- `session.wait.generationComplete()`
+- `session.wait.deployable()` (phasic resolves on `phase_validated`)
+- `session.wait.previewDeployed()`
+- `session.wait.cloudflareDeployed()`
+
+All waits default to a long timeout (10 minutes). You can override per call:
+
+```ts
+await session.wait.generationComplete({ timeoutMs: 2 * 60_000 });
+```
+
+## Reliable WebSocket connections
+
+Connections automatically reconnect with exponential backoff + jitter.
+
+Events:
+
+- `session.on('ws:reconnecting', ({ attempt, delayMs, reason }) => { ... })`
+
+To disable reconnect:
+
+```ts
+session.connect({ retry: { enabled: false } });
+```
+
+## Low-level access
+
+For advanced clients, you can subscribe to the raw typed WS stream:
+
+- `session.on('ws:message', (msg) => { ... })`
+
+The SDK also exposes `ws:raw` when the platform sends malformed/untyped payloads.
+
+## Tests
+
+From `sdk/`:
+
+- Unit: `bun run test`
+- Integration (requires local platform + API key): `bun run test:integration`
+
+Integration expects:
+
+- `VIBESDK_INTEGRATION_API_KEY`
+- optional `VIBESDK_INTEGRATION_BASE_URL` (default `http://localhost:5173`)

package/dist/index.d.ts

@@ -398,7 +398,7 @@ declare const TemplateDetailsSchema: z.ZodObject<{
 	renderMode?: "sandbox" | "browser" | undefined;
 	slideDirectory?: string | undefined;
 }>;
-export type TemplateDetails = z.infer<typeof TemplateDetailsSchema>;
+type TemplateDetails = z.infer<typeof TemplateDetailsSchema>;
 declare const PreviewSchema: z.ZodObject<{
 	runId: z.ZodOptional<z.ZodString>;
 	previewURL: z.ZodOptional<z.ZodString>;
@@ -676,6 +676,14 @@ declare const StaticAnalysisResponseSchema: z.ZodObject<{
 	error?: string | undefined;
 }>;
 type StaticAnalysisResponse = z.infer<typeof StaticAnalysisResponseSchema>;
+type ToolCall = {
+	id: string;
+	type: "function";
+	function: {
+		name: string;
+		arguments: string;
+	};
+};
 type MessageRole = "system" | "user" | "assistant" | "function" | "tool";
 type TextContent = {
 	type: "text";
@@ -689,14 +697,6 @@ type ImageContent = {
 	};
 };
 type MessageContent = string | (TextContent | ImageContent)[] | null;
-type ToolCall = {
-	id: string;
-	type: "function";
-	function: {
-		name: string;
-		arguments: string;
-	};
-};
 type Message = {
 	role: MessageRole;
 	content: MessageContent;
@@ -1326,6 +1326,12 @@ export interface AgentConnectionData {
 	agentId: string;
 }
 export type AgentPreviewResponse = PreviewType;
+type RetryConfig = {
+	enabled?: boolean;
+	initialDelayMs?: number;
+	maxDelayMs?: number;
+	maxRetries?: number;
+};
 type BehaviorType$1 = BehaviorType;
 type ProjectType$1 = ProjectType;
 export type Credentials = NonNullable<CodeGenArgs["credentials"]>;
@@ -1427,13 +1433,24 @@ export type AgentEventMap = {
 	"ws:error": {
 		error: unknown;
 	};
-	/** Raw server->client message */
+	"ws:reconnecting": {
+		attempt: number;
+		delayMs: number;
+		reason: "close" | "error";
+	};
+	/** Server payload that isn't a well-formed typed message. */
+	"ws:raw": {
+		raw: unknown;
+	};
+	/** Raw server->client message (typed) */
 	"ws:message": AgentWsServerMessage;
 	connected: WsMessageOf<"agent_connected">;
 	conversation: WsMessageOf<"conversation_response" | "conversation_state">;
 	phase: WsMessageOf<"phase_generating" | "phase_generated" | "phase_implementing" | "phase_implemented" | "phase_validating" | "phase_validated">;
 	file: WsMessageOf<"file_chunk_generated" | "file_generated" | "file_generating" | "file_regenerating" | "file_regenerated">;
+	generation: WsMessageOf<"generation_started" | "generation_complete" | "generation_stopped" | "generation_resumed">;
 	preview: WsMessageOf<"deployment_completed" | "deployment_started" | "deployment_failed">;
+	cloudflare: WsMessageOf<"cloudflare_deployment_started" | "cloudflare_deployment_completed" | "cloudflare_deployment_error">;
 	/** User-friendly error derived from `{ type: 'error' }` message */
 	error: {
 		error: string;
@@ -1454,6 +1471,16 @@ export type AgentConnectionOptions = {
 	headers?: Record<string, string>;
 	/** Optional WebSocket factory for Node/Bun runtimes. */
 	webSocketFactory?: (url: string, protocols?: string | string[], headers?: Record<string, string>) => WebSocketLike;
+	/**
+	 * Auto-reconnect config (enabled by default).
+	 * Set `{ enabled: false }` to disable.
+	 */
+	retry?: {
+		enabled?: boolean;
+		initialDelayMs?: number;
+		maxDelayMs?: number;
+		maxRetries?: number;
+	};
 };
 export type AgentConnection = {
 	send: (msg: AgentWsClientMessage) => void;
@@ -1462,6 +1489,34 @@ export type AgentConnection = {
 	onAny: (cb: (event: keyof AgentEventMap, payload: AgentEventMap[keyof AgentEventMap]) => void) => () => void;
 	waitFor: <K extends keyof AgentEventMap>(event: K, predicate?: (payload: AgentEventMap[K]) => boolean, timeoutMs?: number) => Promise<AgentEventMap[K]>;
 };
+type FileTreeNode$1 = {
+	type: "dir";
+	name: string;
+	path: string;
+	children: FileTreeNode$1[];
+} | {
+	type: "file";
+	name: string;
+	path: string;
+};
+export type SessionFiles = {
+	listPaths: () => string[];
+	read: (path: string) => string | null;
+	snapshot: () => Record<string, string>;
+	tree: () => FileTreeNode$1[];
+};
+export type WaitOptions = {
+	timeoutMs?: number;
+};
+export type PhaseEventType = "phase_generating" | "phase_generated" | "phase_implementing" | "phase_implemented" | "phase_validating" | "phase_validated";
+export type WaitForPhaseOptions = WaitOptions & {
+	type: PhaseEventType;
+};
+export type SessionDeployable = {
+	files: number;
+	reason: "generation_complete" | "phase_validated";
+	previewUrl?: string;
+};
 export type VibeClientOptions = {
 	baseUrl: string;
 	/**
@@ -1476,9 +1531,106 @@ export type VibeClientOptions = {
 	/** Optional WebSocket factory for Node/Bun runtimes. */
 	webSocketFactory?: AgentConnectionOptions["webSocketFactory"];
 	fetchFn?: typeof fetch;
+	/** HTTP retry configuration for transient failures (5xx, network errors). */
+	retry?: RetryConfig;
 };
-type WaitUntilReadyOptions = {
-	timeoutMs?: number;
+type GenerationState = {
+	status: "idle";
+} | {
+	status: "running";
+	totalFiles?: number;
+} | {
+	status: "stopped";
+	instanceId?: string;
+} | {
+	status: "complete";
+	instanceId?: string;
+	previewURL?: string;
+};
+type PhaseState$1 = {
+	status: "idle";
+} | {
+	status: "generating" | "generated" | "implementing" | "implemented" | "validating" | "validated";
+	name?: string;
+	description?: string;
+};
+type PreviewDeploymentState = {
+	status: "idle";
+} | {
+	status: "running";
+} | {
+	status: "failed";
+	error: string;
+} | {
+	status: "complete";
+	previewURL: string;
+	tunnelURL: string;
+	instanceId: string;
+};
+type CloudflareDeploymentState = {
+	status: "idle";
+} | {
+	status: "running";
+	instanceId?: string;
+} | {
+	status: "failed";
+	error: string;
+	instanceId?: string;
+} | {
+	status: "complete";
+	deploymentUrl: string;
+	instanceId: string;
+	workersUrl?: string;
+};
+type ConversationState$1 = WsMessageOf<"conversation_state">["state"];
+export type SessionState = {
+	conversationState?: ConversationState$1;
+	lastConversationResponse?: WsMessageOf<"conversation_response">;
+	generation: GenerationState;
+	phase: PhaseState$1;
+	/** Best-known preview url (from agent_connected, generation_complete, deployment_completed). */
+	previewUrl?: string;
+	preview: PreviewDeploymentState;
+	cloudflare: CloudflareDeploymentState;
+	lastError?: string;
+};
+export declare class SessionStateStore {
+	private state;
+	private emitter;
+	get(): SessionState;
+	onChange(cb: (next: SessionState, prev: SessionState) => void): () => void;
+	applyWsMessage(msg: AgentWsServerMessage): void;
+	private setState;
+	clear(): void;
+}
+type WorkspaceChange = {
+	type: "reset";
+	files: number;
+} | {
+	type: "upsert";
+	path: string;
+} | {
+	type: "delete";
+	path: string;
+};
+export declare class WorkspaceStore {
+	private files;
+	private emitter;
+	paths(): string[];
+	read(path: string): string | null;
+	snapshot(): Record<string, string>;
+	onChange(cb: (change: WorkspaceChange) => void): () => void;
+	/** Apply authoritative snapshot from an AgentState. */
+	applyStateSnapshot(state: AgentState): void;
+	/** Apply a single file upsert from WS file events. */
+	applyFileUpsert(file: unknown): void;
+	applyWsMessage(msg: AgentWsServerMessage): void;
+	clear(): void;
+}
+type WaitUntilReadyOptions = WaitOptions;
+type BuildSessionConnectOptions = AgentConnectionOptions & {
+	/** If true (default), send `get_conversation_state` on socket open. */
+	autoRequestConversationState?: boolean;
 };
 type BuildSessionInit = {
 	getAuthToken?: () => string | undefined;
@@ -1492,9 +1644,28 @@ export declare class BuildSession {
 	readonly behaviorType: BehaviorType$1 | undefined;
 	readonly projectType: ProjectType$1 | string | undefined;
 	private connection;
+	readonly workspace: WorkspaceStore;
+	readonly state: SessionStateStore;
+	readonly files: SessionFiles;
+	readonly wait: {
+		generationStarted: (options?: WaitOptions) => Promise<{
+			type: "generation_started";
+			message: string;
+			totalFiles: number;
+		}>;
+		generationComplete: (options?: WaitOptions) => Promise<{
+			type: "generation_complete";
+			instanceId?: string;
+			previewURL?: string;
+		}>;
+		phase: (options: WaitForPhaseOptions) => Promise<WsMessageOf<PhaseEventType>>;
+		deployable: (options?: WaitOptions) => Promise<SessionDeployable>;
+		previewDeployed: (options?: WaitOptions) => Promise<DeploymentCompletedMessage>;
+		cloudflareDeployed: (options?: WaitOptions) => Promise<CloudflareDeploymentCompletedMessage>;
+	};
 	constructor(clientOptions: VibeClientOptions, start: BuildStartEvent, init?: BuildSessionInit);
 	isConnected(): boolean;
-	connect(options?: AgentConnectionOptions): AgentConnection;
+	connect(options?: BuildSessionConnectOptions): AgentConnection;
 	startGeneration(): void;
 	stop(): void;
 	followUp(message: string, options?: {
@@ -1503,6 +1674,19 @@ export declare class BuildSession {
 	requestConversationState(): void;
 	deployPreview(): void;
 	deployCloudflare(): void;
+	resume(): void;
+	clearConversation(): void;
+	private getDefaultTimeoutMs;
+	private waitForWsMessage;
+	waitForGenerationStarted(options?: WaitOptions): Promise<WsMessageOf<"generation_started">>;
+	waitForGenerationComplete(options?: WaitOptions): Promise<WsMessageOf<"generation_complete">>;
+	waitForPhase(options: WaitForPhaseOptions): Promise<WsMessageOf<PhaseEventType>>;
+	waitForDeployable(options?: WaitOptions): Promise<SessionDeployable>;
+	waitForPreviewDeployed(options?: WaitOptions): Promise<WsMessageOf<"deployment_completed">>;
+	waitForCloudflareDeployed(options?: WaitOptions): Promise<WsMessageOf<"cloudflare_deployment_completed">>;
+	/**
+	 * Legacy alias. Prefer `session.wait.generationStarted()`.
+	 */
 	waitUntilReady(options?: WaitUntilReadyOptions): Promise<void>;
 	on: AgentConnection["on"];
 	onAny: AgentConnection["onAny"];
@@ -1556,6 +1740,7 @@ export declare class PhasicClient extends VibeClient {
 export {
 	BehaviorType$1 as BehaviorType,
 	CodeGenArgs$1 as CodeGenArgs,
+	FileTreeNode$1 as FileTreeNode,
 	ProjectType$1 as ProjectType,
 };
 

package/dist/index.js

@@ -1,10 +1,40 @@
 // @bun
+// src/retry.ts
+function normalizeRetryConfig(retry, defaults) {
+  return {
+    enabled: retry?.enabled ?? defaults.enabled,
+    initialDelayMs: retry?.initialDelayMs ?? defaults.initialDelayMs,
+    maxDelayMs: retry?.maxDelayMs ?? defaults.maxDelayMs,
+    maxRetries: retry?.maxRetries ?? defaults.maxRetries
+  };
+}
+function computeBackoffMs(attempt, cfg) {
+  const base = Math.min(cfg.maxDelayMs, cfg.initialDelayMs * Math.pow(2, Math.max(0, attempt)));
+  const jitter = base * 0.2;
+  return Math.max(0, Math.floor(base - jitter + Math.random() * jitter * 2));
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 // src/http.ts
+var HTTP_RETRY_DEFAULTS = {
+  enabled: true,
+  initialDelayMs: 1000,
+  maxDelayMs: 1e4,
+  maxRetries: 3
+};
+function isRetryableStatus(status) {
+  return status >= 500 && status < 600;
+}
+
 class HttpClient {
   opts;
   cachedAccessToken = null;
+  retryCfg;
   constructor(opts) {
     this.opts = opts;
+    this.retryCfg = normalizeRetryConfig(opts.retry, HTTP_RETRY_DEFAULTS);
   }
   get baseUrl() {
     return this.opts.baseUrl.replace(/\/$/, "");
@@ -34,7 +64,10 @@ class HttpClient {
       }
     });
     if (!resp.ok) {
-      const text = await resp.text().catch(() => "");
+      const text = (await resp.text().catch(() => "")).slice(0, 1000);
+      if (resp.status === 401) {
+        throw new Error(`HTTP 401 for /api/auth/exchange-api-key: invalid API key (regenerate in Settings \u2192 API Keys). ${text || ""}`.trim());
+      }
       throw new Error(`HTTP ${resp.status} for /api/auth/exchange-api-key: ${text || resp.statusText}`);
     }
     const parsed = await resp.json();
@@ -57,21 +90,59 @@ class HttpClient {
   }
   async fetchJson(path, init) {
     const url = `${this.baseUrl}${path}`;
-    const resp = await this.fetchFn(url, init);
-    if (!resp.ok) {
-      const text = await resp.text().catch(() => "");
-      throw new Error(`HTTP ${resp.status} for ${path}: ${text || resp.statusText}`);
+    let lastError = null;
+    for (let attempt = 0;attempt <= this.retryCfg.maxRetries; attempt++) {
+      try {
+        const resp = await this.fetchFn(url, init);
+        if (!resp.ok) {
+          const text = (await resp.text().catch(() => "")).slice(0, 1000);
+          const error = new Error(`HTTP ${resp.status} for ${path}: ${text || resp.statusText}`);
+          if (this.retryCfg.enabled && isRetryableStatus(resp.status) && attempt < this.retryCfg.maxRetries) {
+            lastError = error;
+            await sleep(computeBackoffMs(attempt, this.retryCfg));
+            continue;
+          }
+          throw error;
+        }
+        return await resp.json();
+      } catch (error) {
+        if (error instanceof TypeError && this.retryCfg.enabled && attempt < this.retryCfg.maxRetries) {
+          lastError = error;
+          await sleep(computeBackoffMs(attempt, this.retryCfg));
+          continue;
+        }
+        throw error;
+      }
     }
-    return await resp.json();
+    throw lastError ?? new Error(`Failed after ${this.retryCfg.maxRetries} retries`);
   }
   async fetchRaw(path, init) {
     const url = `${this.baseUrl}${path}`;
-    const resp = await this.fetchFn(url, init);
-    if (!resp.ok) {
-      const text = await resp.text().catch(() => "");
-      throw new Error(`HTTP ${resp.status} for ${path}: ${text || resp.statusText}`);
+    let lastError = null;
+    for (let attempt = 0;attempt <= this.retryCfg.maxRetries; attempt++) {
+      try {
+        const resp = await this.fetchFn(url, init);
+        if (!resp.ok) {
+          const text = (await resp.text().catch(() => "")).slice(0, 1000);
+          const error = new Error(`HTTP ${resp.status} for ${path}: ${text || resp.statusText}`);
+          if (this.retryCfg.enabled && isRetryableStatus(resp.status) && attempt < this.retryCfg.maxRetries) {
+            lastError = error;
+            await sleep(computeBackoffMs(attempt, this.retryCfg));
+            continue;
+          }
+          throw error;
+        }
+        return resp;
+      } catch (error) {
+        if (error instanceof TypeError && this.retryCfg.enabled && attempt < this.retryCfg.maxRetries) {
+          lastError = error;
+          await sleep(computeBackoffMs(attempt, this.retryCfg));
+          continue;
+        }
+        throw error;
+      }
     }
-    return resp;
+    throw lastError ?? new Error(`Failed after ${this.retryCfg.maxRetries} retries`);
   }
 }
 
@@ -134,6 +205,177 @@ class TypedEmitter {
     for (const cb of set)
       cb(payload);
   }
+  clear() {
+    this.listeners.clear();
+    this.anyListeners.clear();
+  }
+}
+
+// src/state.ts
+var INITIAL_STATE = {
+  generation: { status: "idle" },
+  phase: { status: "idle" },
+  preview: { status: "idle" },
+  cloudflare: { status: "idle" }
+};
+function extractPhaseInfo(msg) {
+  const phase = msg?.phase;
+  return {
+    name: phase?.name,
+    description: phase?.description
+  };
+}
+
+class SessionStateStore {
+  state = INITIAL_STATE;
+  emitter = new TypedEmitter;
+  get() {
+    return this.state;
+  }
+  onChange(cb) {
+    return this.emitter.on("change", ({ prev, next }) => cb(next, prev));
+  }
+  applyWsMessage(msg) {
+    switch (msg.type) {
+      case "conversation_state": {
+        const m = msg;
+        this.setState({ conversationState: m.state });
+        break;
+      }
+      case "conversation_response": {
+        const m = msg;
+        this.setState({ lastConversationResponse: m });
+        break;
+      }
+      case "generation_started": {
+        const m = msg;
+        this.setState({ generation: { status: "running", totalFiles: m.totalFiles } });
+        break;
+      }
+      case "generation_complete": {
+        const m = msg;
+        const previewURL = m.previewURL;
+        this.setState({
+          generation: {
+            status: "complete",
+            instanceId: m.instanceId,
+            previewURL
+          },
+          ...previewURL ? { previewUrl: previewURL } : {}
+        });
+        break;
+      }
+      case "generation_stopped": {
+        const m = msg;
+        this.setState({ generation: { status: "stopped", instanceId: m.instanceId } });
+        break;
+      }
+      case "generation_resumed": {
+        this.setState({ generation: { status: "running" } });
+        break;
+      }
+      case "phase_generating": {
+        const m = msg;
+        this.setState({ phase: { status: "generating", ...extractPhaseInfo(m) } });
+        break;
+      }
+      case "phase_generated": {
+        const m = msg;
+        this.setState({ phase: { status: "generated", ...extractPhaseInfo(m) } });
+        break;
+      }
+      case "phase_implementing": {
+        const m = msg;
+        this.setState({ phase: { status: "implementing", ...extractPhaseInfo(m) } });
+        break;
+      }
+      case "phase_implemented": {
+        const m = msg;
+        this.setState({ phase: { status: "implemented", ...extractPhaseInfo(m) } });
+        break;
+      }
+      case "phase_validating": {
+        const m = msg;
+        this.setState({ phase: { status: "validating", ...extractPhaseInfo(m) } });
+        break;
+      }
+      case "phase_validated": {
+        const m = msg;
+        this.setState({ phase: { status: "validated", ...extractPhaseInfo(m) } });
+        break;
+      }
+      case "deployment_started": {
+        this.setState({ preview: { status: "running" } });
+        break;
+      }
+      case "deployment_failed": {
+        const m = msg;
+        this.setState({ preview: { status: "failed", error: m.error } });
+        break;
+      }
+      case "deployment_completed": {
+        const m = msg;
+        this.setState({
+          previewUrl: m.previewURL,
+          preview: {
+            status: "complete",
+            previewURL: m.previewURL,
+            tunnelURL: m.tunnelURL,
+            instanceId: m.instanceId
+          }
+        });
+        break;
+      }
+      case "cloudflare_deployment_started": {
+        const m = msg;
+        this.setState({ cloudflare: { status: "running", instanceId: m.instanceId } });
+        break;
+      }
+      case "cloudflare_deployment_error": {
+        const m = msg;
+        this.setState({
+          cloudflare: { status: "failed", error: m.error, instanceId: m.instanceId }
+        });
+        break;
+      }
+      case "cloudflare_deployment_completed": {
+        const m = msg;
+        this.setState({
+          cloudflare: {
+            status: "complete",
+            deploymentUrl: m.deploymentUrl,
+            workersUrl: m.workersUrl,
+            instanceId: m.instanceId
+          }
+        });
+        break;
+      }
+      case "agent_connected": {
+        const m = msg;
+        const previewUrl = m.previewUrl;
+        if (previewUrl)
+          this.setState({ previewUrl });
+        break;
+      }
+      case "error": {
+        const m = msg;
+        this.setState({ lastError: m.error });
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  setState(patch) {
+    const prev = this.state;
+    const next = { ...prev, ...patch };
+    this.state = next;
+    this.emitter.emit("change", { prev, next });
+  }
+  clear() {
+    this.state = INITIAL_STATE;
+    this.emitter.clear();
+  }
 }
 
 // src/ws.ts
@@ -143,39 +385,121 @@ function toWsCloseEvent(ev) {
     reason: typeof ev.reason === "string" ? ev.reason : ""
   };
 }
+var WS_RETRY_DEFAULTS = {
+  enabled: true,
+  initialDelayMs: 1000,
+  maxDelayMs: 30000,
+  maxRetries: Infinity
+};
 function createAgentConnection(url, options = {}) {
   const emitter = new TypedEmitter;
+  const retryCfg = normalizeRetryConfig(options.retry, WS_RETRY_DEFAULTS);
   const headers = { ...options.headers ?? {} };
   if (options.origin)
     headers.Origin = options.origin;
-  const ws = options.webSocketFactory ? options.webSocketFactory(url, undefined, headers) : new WebSocket(url);
-  if (ws.addEventListener) {
-    ws.addEventListener("open", () => {
-      emitter.emit("ws:open", undefined);
-    });
-    ws.addEventListener("close", (ev) => {
-      emitter.emit("ws:close", toWsCloseEvent(ev));
-    });
-    ws.addEventListener("error", (ev) => {
-      emitter.emit("ws:error", { error: ev });
-    });
-    ws.addEventListener("message", (ev) => {
-      handleMessage(ev.data);
-    });
-  } else if (ws.on) {
-    ws.on("open", () => emitter.emit("ws:open", undefined));
-    ws.on("close", (code, reason) => {
-      emitter.emit("ws:close", {
-        code: typeof code === "number" ? code : 1000,
-        reason: typeof reason === "string" ? reason : ""
-      });
+  let ws = null;
+  let isOpen = false;
+  let closedByUser = false;
+  let reconnectAttempts = 0;
+  let reconnectTimer = null;
+  const pendingSends = [];
+  const maxPendingSends = 1000;
+  function clearReconnectTimer() {
+    if (!reconnectTimer)
+      return;
+    clearTimeout(reconnectTimer);
+    reconnectTimer = null;
+  }
+  function makeWebSocket() {
+    if (options.webSocketFactory)
+      return options.webSocketFactory(url, undefined, headers);
+    return new WebSocket(url);
+  }
+  function flushPendingSends() {
+    if (!ws || !isOpen)
+      return;
+    for (const data of pendingSends)
+      ws.send(data);
+    pendingSends.length = 0;
+  }
+  function scheduleReconnect(reason) {
+    if (closedByUser)
+      return;
+    if (!retryCfg.enabled)
+      return;
+    if (reconnectAttempts >= retryCfg.maxRetries)
+      return;
+    if (reconnectTimer)
+      return;
+    const delayMs = computeBackoffMs(reconnectAttempts, retryCfg);
+    emitter.emit("ws:reconnecting", {
+      attempt: reconnectAttempts + 1,
+      delayMs,
+      reason
     });
-    ws.on("error", (error) => emitter.emit("ws:error", { error }));
-    ws.on("message", (data) => handleMessage(data));
+    reconnectAttempts += 1;
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      connectNow();
+    }, delayMs);
+  }
+  function onOpen() {
+    isOpen = true;
+    reconnectAttempts = 0;
+    emitter.emit("ws:open", undefined);
+    flushPendingSends();
+  }
+  function onClose(ev) {
+    isOpen = false;
+    emitter.emit("ws:close", toWsCloseEvent(ev));
+    scheduleReconnect("close");
+  }
+  function onError(error) {
+    emitter.emit("ws:error", { error });
+    scheduleReconnect("error");
+  }
+  function looksLikeAgentState(obj) {
+    if (!obj || typeof obj !== "object")
+      return false;
+    const behaviorType = obj.behaviorType;
+    const projectType = obj.projectType;
+    return typeof behaviorType === "string" && typeof projectType === "string";
+  }
+  function normalizeServerPayload(raw) {
+    if (!raw || typeof raw !== "object")
+      return null;
+    const t = raw.type;
+    if (typeof t === "string") {
+      const trimmed = t.trim();
+      if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+        try {
+          const inner = JSON.parse(trimmed);
+          const normalizedInner = normalizeServerPayload(inner);
+          if (normalizedInner)
+            return normalizedInner;
+          emitter.emit("ws:raw", { raw: inner });
+          return null;
+        } catch {}
+      }
+      return raw;
+    }
+    const state = raw.state;
+    if (looksLikeAgentState(state)) {
+      return { type: "cf_agent_state", state };
+    }
+    if (looksLikeAgentState(raw)) {
+      return { type: "cf_agent_state", state: raw };
+    }
+    return null;
   }
-  function handleMessage(data) {
+  function onMessage(data) {
     try {
-      const parsed = JSON.parse(String(data));
+      const raw = JSON.parse(String(data));
+      const parsed = normalizeServerPayload(raw);
+      if (!parsed) {
+        emitter.emit("ws:raw", { raw });
+        return;
+      }
       emitter.emit("ws:message", parsed);
       switch (parsed.type) {
         case "agent_connected":
@@ -200,11 +524,22 @@ function createAgentConnection(url, options = {}) {
         case "file_regenerated":
           emitter.emit("file", parsed);
           break;
+        case "generation_started":
+        case "generation_complete":
+        case "generation_stopped":
+        case "generation_resumed":
+          emitter.emit("generation", parsed);
+          break;
         case "deployment_completed":
         case "deployment_started":
         case "deployment_failed":
           emitter.emit("preview", parsed);
           break;
+        case "cloudflare_deployment_started":
+        case "cloudflare_deployment_completed":
+        case "cloudflare_deployment_error":
+          emitter.emit("cloudflare", parsed);
+          break;
         case "error":
           emitter.emit("error", { error: String(parsed.error ?? "Unknown error") });
           break;
@@ -212,14 +547,56 @@ function createAgentConnection(url, options = {}) {
           break;
       }
     } catch (error) {
-      emitter.emit("ws:error", { error });
+      onError(error);
     }
   }
+  function connectNow() {
+    if (closedByUser)
+      return;
+    clearReconnectTimer();
+    try {
+      ws = makeWebSocket();
+    } catch (error) {
+      onError(error);
+      scheduleReconnect("error");
+      return;
+    }
+    if (ws.addEventListener) {
+      ws.addEventListener("open", () => onOpen());
+      ws.addEventListener("close", (ev) => onClose(ev));
+      ws.addEventListener("error", (ev) => onError(ev));
+      ws.addEventListener("message", (ev) => onMessage(ev.data));
+      return;
+    }
+    if (ws.on) {
+      ws.on("open", () => onOpen());
+      ws.on("close", (code, reason) => onClose({ code: typeof code === "number" ? code : undefined, reason: typeof reason === "string" ? reason : undefined }));
+      ws.on("error", (error) => onError(error));
+      ws.on("message", (data) => onMessage(data));
+    }
+  }
+  connectNow();
   function send(msg) {
-    ws.send(JSON.stringify(msg));
+    const data = JSON.stringify(msg);
+    if (isOpen && ws) {
+      ws.send(data);
+      return;
+    }
+    pendingSends.push(data);
+    if (pendingSends.length > maxPendingSends) {
+      pendingSends.shift();
+      emitter.emit("ws:error", {
+        error: new Error(`Message queue overflow: dropped oldest message (queue size: ${maxPendingSends})`)
+      });
+    }
   }
   function close() {
-    ws.close();
+    closedByUser = true;
+    isOpen = false;
+    pendingSends.length = 0;
+    clearReconnectTimer();
+    ws?.close();
+    ws = null;
   }
   async function waitFor(event, predicate, timeoutMs = 60000) {
     return new Promise((resolve, reject) => {
@@ -245,7 +622,121 @@ function createAgentConnection(url, options = {}) {
   };
 }
 
+// src/workspace.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isFileOutputType(value) {
+  if (!isRecord(value))
+    return false;
+  return typeof value.filePath === "string" && typeof value.fileContents === "string";
+}
+function extractGeneratedFilesFromState(state) {
+  const out = [];
+  for (const file of Object.values(state.generatedFilesMap ?? {})) {
+    if (!isFileOutputType(file))
+      continue;
+    out.push({ path: file.filePath, content: file.fileContents });
+  }
+  return out;
+}
+function extractGeneratedFileFromMessageFile(file) {
+  if (!isFileOutputType(file))
+    return null;
+  return { path: file.filePath, content: file.fileContents };
+}
+
+class WorkspaceStore {
+  files = new Map;
+  emitter = new TypedEmitter;
+  paths() {
+    return Array.from(this.files.keys()).sort();
+  }
+  read(path) {
+    return this.files.get(path) ?? null;
+  }
+  snapshot() {
+    const out = {};
+    for (const [path, content] of this.files.entries())
+      out[path] = content;
+    return out;
+  }
+  onChange(cb) {
+    return this.emitter.on("change", cb);
+  }
+  applyStateSnapshot(state) {
+    this.files.clear();
+    for (const f of extractGeneratedFilesFromState(state)) {
+      this.files.set(f.path, f.content);
+    }
+    this.emitter.emit("change", { type: "reset", files: this.files.size });
+  }
+  applyFileUpsert(file) {
+    const f = extractGeneratedFileFromMessageFile(file);
+    if (!f)
+      return;
+    this.files.set(f.path, f.content);
+    this.emitter.emit("change", { type: "upsert", path: f.path });
+  }
+  applyWsMessage(msg) {
+    switch (msg.type) {
+      case "agent_connected":
+        this.applyStateSnapshot(msg.state);
+        break;
+      case "cf_agent_state":
+        this.applyStateSnapshot(msg.state);
+        break;
+      case "file_generated":
+        this.applyFileUpsert(msg.file);
+        break;
+      case "file_regenerated":
+        this.applyFileUpsert(msg.file);
+        break;
+      default:
+        break;
+    }
+  }
+  clear() {
+    this.files.clear();
+    this.emitter.clear();
+  }
+}
+
 // src/session.ts
+function buildFileTree(paths) {
+  const root = { name: "", path: "", dirs: new Map, files: [] };
+  for (const p of paths) {
+    const parts = p.split("/").filter(Boolean);
+    let curr = root;
+    for (let i = 0;i < parts.length; i += 1) {
+      const part = parts[i];
+      const isLast = i === parts.length - 1;
+      if (isLast) {
+        curr.files.push({ type: "file", name: part, path: p });
+        continue;
+      }
+      const nextPath = curr.path ? `${curr.path}/${part}` : part;
+      let next = curr.dirs.get(part);
+      if (!next) {
+        next = { name: part, path: nextPath, dirs: new Map, files: [] };
+        curr.dirs.set(part, next);
+      }
+      curr = next;
+    }
+  }
+  function toNodes(dir) {
+    const dirs = Array.from(dir.dirs.values()).sort((a, b) => a.name.localeCompare(b.name)).map((d) => ({
+      type: "dir",
+      name: d.name,
+      path: d.path,
+      children: toNodes(d)
+    }));
+    const files = dir.files.sort((a, b) => a.name.localeCompare(b.name));
+    return [...dirs, ...files];
+  }
+  return toNodes(root);
+}
+
 class BuildSession {
   clientOptions;
   init;
@@ -254,6 +745,22 @@ class BuildSession {
   behaviorType;
   projectType;
   connection = null;
+  workspace = new WorkspaceStore;
+  state = new SessionStateStore;
+  files = {
+    listPaths: () => this.workspace.paths(),
+    read: (path) => this.workspace.read(path),
+    snapshot: () => this.workspace.snapshot(),
+    tree: () => buildFileTree(this.workspace.paths())
+  };
+  wait = {
+    generationStarted: (options = {}) => this.waitForGenerationStarted(options),
+    generationComplete: (options = {}) => this.waitForGenerationComplete(options),
+    phase: (options) => this.waitForPhase(options),
+    deployable: (options = {}) => this.waitForDeployable(options),
+    previewDeployed: (options = {}) => this.waitForPreviewDeployed(options),
+    cloudflareDeployed: (options = {}) => this.waitForCloudflareDeployed(options)
+  };
   constructor(clientOptions, start, init = {}) {
     this.clientOptions = clientOptions;
     this.init = init;
@@ -268,29 +775,38 @@ class BuildSession {
   connect(options = {}) {
     if (this.connection)
       return this.connection;
-    const origin = options.origin ?? this.clientOptions.websocketOrigin;
-    const webSocketFactory = options.webSocketFactory ?? this.clientOptions.webSocketFactory;
-    const headers = { ...options.headers ?? {} };
+    const { autoRequestConversationState, ...agentOptions } = options;
+    const origin = agentOptions.origin ?? this.clientOptions.websocketOrigin;
+    const webSocketFactory = agentOptions.webSocketFactory ?? this.clientOptions.webSocketFactory;
+    const headers = { ...agentOptions.headers ?? {} };
     const token = this.init.getAuthToken?.();
     if (token && !headers.Authorization) {
       headers.Authorization = `Bearer ${token}`;
     }
     const connectOptions = {
-      ...options,
+      ...agentOptions,
       ...origin ? { origin } : {},
       ...Object.keys(headers).length ? { headers } : {},
       ...webSocketFactory ? { webSocketFactory } : {}
     };
     this.connection = createAgentConnection(this.websocketUrl, connectOptions);
-    const credentials = options.credentials ?? this.init.defaultCredentials;
-    if (credentials) {
-      this.connection.on("ws:open", () => {
+    this.connection.on("ws:message", (m) => {
+      this.workspace.applyWsMessage(m);
+      this.state.applyWsMessage(m);
+    });
+    const credentials = agentOptions.credentials ?? this.init.defaultCredentials;
+    const shouldRequestConversationState = autoRequestConversationState ?? true;
+    this.connection.on("ws:open", () => {
+      if (credentials) {
         this.connection?.send({
           type: "session_init",
           credentials
         });
-      });
-    }
+      }
+      if (shouldRequestConversationState) {
+        this.connection?.send({ type: "get_conversation_state" });
+      }
+    });
     return this.connection;
   }
   startGeneration() {
@@ -321,15 +837,65 @@ class BuildSession {
     this.assertConnected();
     this.connection.send({ type: "deploy" });
   }
-  async waitUntilReady(options = {}) {
+  resume() {
     this.assertConnected();
-    const timeoutMs = options.timeoutMs ?? 120000;
-    const behavior = this.behaviorType;
-    if (behavior === "phasic") {
-      await this.connection.waitFor("phase", (payload) => payload.type === "phase_implementing", timeoutMs);
-      return;
+    this.connection.send({ type: "resume_generation" });
+  }
+  clearConversation() {
+    this.assertConnected();
+    this.connection.send({ type: "clear_conversation" });
+  }
+  getDefaultTimeoutMs() {
+    return 10 * 60000;
+  }
+  async waitForWsMessage(predicate, timeoutMs) {
+    this.assertConnected();
+    return await this.connection.waitFor("ws:message", predicate, timeoutMs);
+  }
+  async waitForGenerationStarted(options = {}) {
+    return await this.waitForMessageType("generation_started", options.timeoutMs ?? this.getDefaultTimeoutMs());
+  }
+  async waitForGenerationComplete(options = {}) {
+    return await this.waitForMessageType("generation_complete", options.timeoutMs ?? this.getDefaultTimeoutMs());
+  }
+  async waitForPhase(options) {
+    return await this.waitForMessageType(options.type, options.timeoutMs ?? this.getDefaultTimeoutMs());
+  }
+  async waitForDeployable(options = {}) {
+    const timeoutMs = options.timeoutMs ?? this.getDefaultTimeoutMs();
+    if (this.behaviorType === "phasic") {
+      await this.waitForPhase({ type: "phase_validated", timeoutMs });
+      return {
+        files: this.workspace.paths().length,
+        reason: "phase_validated",
+        previewUrl: this.state.get().previewUrl
+      };
+    }
+    await this.waitForGenerationComplete({ timeoutMs });
+    return {
+      files: this.workspace.paths().length,
+      reason: "generation_complete",
+      previewUrl: this.state.get().previewUrl
+    };
+  }
+  async waitForPreviewDeployed(options = {}) {
+    const timeoutMs = options.timeoutMs ?? this.getDefaultTimeoutMs();
+    const msg = await this.waitForWsMessage((m) => m.type === "deployment_completed" || m.type === "deployment_failed", timeoutMs);
+    if (msg.type === "deployment_failed") {
+      throw new Error(msg.error);
+    }
+    return msg;
+  }
+  async waitForCloudflareDeployed(options = {}) {
+    const timeoutMs = options.timeoutMs ?? this.getDefaultTimeoutMs();
+    const msg = await this.waitForWsMessage((m) => m.type === "cloudflare_deployment_completed" || m.type === "cloudflare_deployment_error", timeoutMs);
+    if (msg.type === "cloudflare_deployment_error") {
+      throw new Error(msg.error);
     }
-    await this.connection.waitFor("conversation", (payload) => payload.type === "conversation_response", timeoutMs);
+    return msg;
+  }
+  async waitUntilReady(options = {}) {
+    await this.waitForGenerationStarted(options);
   }
   on = (event, cb) => {
     this.assertConnected();
@@ -348,11 +914,13 @@ class BuildSession {
   }
   async waitForMessageType(type, timeoutMs) {
     this.assertConnected();
-    return await this.connection.waitFor("ws:message", (msg) => msg.type === type, timeoutMs);
+    return await this.connection.waitFor("ws:message", (msg) => msg.type === type, timeoutMs ?? this.getDefaultTimeoutMs());
   }
   close() {
     this.connection?.close();
     this.connection = null;
+    this.workspace.clear();
+    this.state.clear();
   }
   assertConnected() {
     if (!this.connection) {
@@ -494,7 +1062,9 @@ class PhasicClient extends VibeClient {
   }
 }
 export {
+  WorkspaceStore,
   VibeClient,
+  SessionStateStore,
   PhasicClient,
   BuildSession,
   AgenticClient

package/dist/node.d.ts

@@ -61,6 +61,16 @@ type AgentConnectionOptions = {
 	headers?: Record<string, string>;
 	/** Optional WebSocket factory for Node/Bun runtimes. */
 	webSocketFactory?: (url: string, protocols?: string | string[], headers?: Record<string, string>) => WebSocketLike;
+	/**
+	 * Auto-reconnect config (enabled by default).
+	 * Set `{ enabled: false }` to disable.
+	 */
+	retry?: {
+		enabled?: boolean;
+		initialDelayMs?: number;
+		maxDelayMs?: number;
+		maxRetries?: number;
+	};
 };
 export declare function createNodeWebSocketFactory(): NonNullable<AgentConnectionOptions["webSocketFactory"]>;
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cf-vibesdk/sdk",
-	"version": "0.0.1",
+	"version": "0.0.3",
 	"type": "module",
 	"exports": {
 		".": {
@@ -22,8 +22,8 @@
 		"build": "rm -rf ./dist && bun build ./src/index.ts ./src/node.ts --outdir ./dist --target bun",
 		"bundle-types": "dts-bundle-generator --export-referenced-types false --project ./tsconfig.protocol.json -o ./dist/index.d.ts ./src/index.ts && dts-bundle-generator --export-referenced-types false --project ./tsconfig.protocol.json -o ./dist/node.d.ts ./src/node.ts",
 		"typecheck": "tsc -p ./tsconfig.json --noEmit",
-		"test": "bun test",
-		"example:cli": "bun ./src/example/cli.ts"
+		"test": "bun test test/*.test.ts",
+		"test:integration": "bun test --timeout 600000 test/integration/*.test.ts"
 	},
 	"dependencies": {
 		"ws": "^8.18.3"
@@ -35,3 +35,4 @@
 	}
 }
 
+