@cf-vibesdk/sdk 0.0.8 → 0.1.0

package/README.md

@@ -94,6 +94,53 @@ const session = await client.build('Build a weather dashboard', {
 });
 ```
 
+#### Blueprint Streaming
+
+The server streams blueprint chunks as the AI generates the project plan. By default, `build()` waits for all chunks before returning:
+
+```ts
+// Default behavior: waits for blueprint to complete
+const session = await client.build('Build a todo app', {
+  onBlueprintChunk: (chunk) => {
+    // Called in real-time as chunks arrive
+    blueprintText += chunk;
+  },
+});
+// Session returned after all blueprint chunks received
+```
+
+For faster startup, set `waitForBlueprint: false` to return immediately and stream chunks in the background:
+
+```ts
+const session = await client.build('Build a todo app', {
+  waitForBlueprint: false,  // Return immediately after start event
+  onBlueprintChunk: (chunk) => {
+    // Still called in real-time as chunks arrive
+    blueprintText += chunk;
+  },
+  onBlueprintError: (error) => {
+    // Called if streaming fails (session is auto-closed)
+    console.error('Blueprint streaming failed:', error);
+  },
+});
+// Session returned immediately, blueprint streams in background
+```
+
+Use the `BlueprintStreamParser` utility to convert chunks to readable Markdown:
+
+```ts
+import { BlueprintStreamParser } from '@cf-vibesdk/sdk';
+
+const parser = new BlueprintStreamParser();
+const session = await client.build('Build a todo app', {
+  waitForBlueprint: false,
+  onBlueprintChunk: (chunk) => {
+    const markdown = parser.append(chunk);
+    console.log(markdown);  // Rendered as Markdown
+  },
+});
+```
+
 ### `client.connect(agentId)`
 
 Connect to an existing app session. State is automatically restored from the agent, including:
@@ -250,6 +297,24 @@ if (session.phases.allCompleted()) {
 
 // Get phase by ID
 const phase = session.phases.get('phase-0');
+
+// Subscribe to phase changes
+const unsubscribe = session.phases.onChange((event) => {
+  console.log(`Phase ${event.type}:`, event.phase.name);
+  console.log(`Status: ${event.phase.status}`);
+  console.log(`Total phases: ${event.allPhases.length}`);
+});
+// Later: unsubscribe();
+```
+
+The `onChange` callback receives a `PhaseTimelineEvent`:
+
+```ts
+type PhaseTimelineEvent = {
+  type: 'added' | 'updated';  // New phase vs status/file change
+  phase: PhaseInfo;           // The affected phase
+  allPhases: PhaseInfo[];     // All phases after this change
+};
 ```
 
 Each phase contains:
@@ -304,14 +369,14 @@ session.workspace.onChange((change) => {
 
 ## WebSocket Reliability
 
-Connections automatically reconnect with exponential backoff.
+Connections automatically reconnect with exponential backoff. The first reconnect attempt is **immediate** (0ms delay) for fast recovery from brief network blips, followed by exponential backoff starting at 200ms.
 
 ```ts
 // Custom retry config
 await session.connect({
   retry: {
     enabled: true,        // Default: true
-    initialDelayMs: 1000, // Default: 1000
+    initialDelayMs: 200,  // Default: 200 (used from 2nd attempt onward)
     maxDelayMs: 30000,    // Default: 30000
     maxRetries: 10,       // Default: Infinity
   },
@@ -321,6 +386,35 @@ await session.connect({
 await session.connect({ retry: { enabled: false } });
 ```
 
+### Auto-Preview on Reconnect
+
+When connecting to an **existing app** (via `client.connect()`), the SDK automatically sends a `preview` message on connect and reconnect to ensure the preview deployment stays active:
+
+```ts
+// Existing app - auto-preview is enabled by default
+const session = await client.connect('agent-id');
+await session.connect();  // Sends preview message automatically
+
+// Override for new builds or disable
+await session.connect({ autoRequestPreview: false });
+
+// Force enable for new builds
+const session = await client.build('Build a todo app');
+await session.connect({ autoRequestPreview: true });
+```
+
+### Reconnect Events
+
+```ts
+session.on('ws:reconnecting', ({ attempt, delayMs, reason }) => {
+  console.log(`Reconnecting (attempt ${attempt}, delay ${delayMs}ms, reason: ${reason})`);
+});
+
+session.on('ws:reconnected', () => {
+  console.log('Reconnected successfully');
+});
+```
+
 ## HTTP Retry
 
 HTTP requests automatically retry on 5xx errors.
@@ -403,6 +497,8 @@ import type {
   PhaseStatus,
   PhaseFileStatus,
   PhaseEventType,
+  PhaseTimelineEvent,
+  PhaseTimelineChangeType,
   
   // API
   ApiResponse,

package/dist/index.d.ts

@@ -5453,7 +5453,21 @@ type CodeGenArgs$1 = CodeGenArgs;
 export type BuildOptions = Omit<CodeGenArgs$1, "query"> & {
 	autoConnect?: boolean;
 	autoGenerate?: boolean;
+	/**
+	 * Called for each blueprint chunk as it streams from the server.
+	 */
 	onBlueprintChunk?: (chunk: string) => void;
+	/**
+	 * Called if blueprint streaming fails. The session will be closed automatically.
+	 * Only relevant when `waitForBlueprint` is false.
+	 */
+	onBlueprintError?: (error: Error) => void;
+	/**
+	 * If true (default), `build()` waits for all blueprint chunks before returning.
+	 * If false, `build()` returns immediately after receiving the start event,
+	 * and blueprint chunks stream in the background via `onBlueprintChunk`.
+	 */
+	waitForBlueprint?: boolean;
 };
 type TemplateFiles = Record<string, string>;
 export type BuildStartEvent = {
@@ -5554,6 +5568,7 @@ export type AgentEventMap = {
 		delayMs: number;
 		reason: "close" | "error";
 	};
+	"ws:reconnected": undefined;
 	"ws:raw": {
 		raw: unknown;
 	};
@@ -5568,6 +5583,8 @@ export type AgentEventMap = {
 	error: {
 		error: string;
 	};
+	/** Emitted when the phase timeline changes (phase added or updated). */
+	phases: PhaseTimelineEvent;
 };
 /**
  * URL provider for WebSocket connections.
@@ -5657,6 +5674,18 @@ export type SessionPhases = {
 	/** Check if all phases are completed. */
 	allCompleted: () => boolean;
 };
+/**
+ * Event emitted when the phase timeline changes.
+ */
+export type PhaseTimelineChangeType = "added" | "updated";
+export type PhaseTimelineEvent = {
+	/** Type of change: 'added' for new phase, 'updated' for status/file changes. */
+	type: PhaseTimelineChangeType;
+	/** The phase that was added or updated. */
+	phase: PhaseInfo;
+	/** All phases in the timeline after this change. */
+	allPhases: PhaseInfo[];
+};
 export type SessionDeployable = {
 	files: number;
 	reason: "generation_complete" | "phase_validated";
@@ -5759,6 +5788,11 @@ export declare class SessionStateStore {
 	private emitter;
 	get(): SessionState;
 	onChange(cb: (next: SessionState, prev: SessionState) => void): () => void;
+	/**
+	 * Subscribe to phase timeline changes.
+	 * Fires when a phase is added or when a phase's status/files change.
+	 */
+	onPhaseChange(cb: (event: PhaseTimelineEvent) => void): () => void;
 	setConnection(state: ConnectionState): void;
 	applyWsMessage(msg: AgentWsServerMessage): void;
 	/**
@@ -5770,6 +5804,14 @@ export declare class SessionStateStore {
 	 */
 	private updateOrAddPhase;
 	private setState;
+	/**
+	 * Compare old and new phases arrays and emit change events.
+	 */
+	private emitPhaseChanges;
+	/**
+	 * Check if a phase has meaningfully changed (status or file statuses).
+	 */
+	private hasPhaseChanged;
 	clear(): void;
 }
 type WorkspaceChange = {
@@ -5822,12 +5864,19 @@ type WaitUntilReadyOptions = WaitOptions;
 type BuildSessionConnectOptions = Omit<AgentConnectionOptions, "credentials"> & {
 	/** If true (default), send `get_conversation_state` on socket open. */
 	autoRequestConversationState?: boolean;
+	/**
+	 * If true, send `preview` message on connect and reconnect to ensure preview exists.
+	 * Defaults to true for existing apps (via `client.connect()`), false for new builds.
+	 */
+	autoRequestPreview?: boolean;
 	/** Credentials to send via session_init after connection. */
 	credentials?: Credentials;
 };
 type BuildSessionInit = {
 	httpClient: HttpClient;
 	defaultCredentials?: Credentials;
+	/** True if this session is for an existing app (via client.connect). */
+	isExistingApp?: boolean;
 };
 export declare class BuildSession {
 	private init;
@@ -5856,6 +5905,12 @@ export declare class BuildSession {
 		count: () => number;
 		/** Check if all phases are completed. */
 		allCompleted: () => boolean;
+		/**
+		 * Subscribe to phase timeline changes.
+		 * Fires when a phase is added or when a phase's status/files change.
+		 * @returns Unsubscribe function.
+		 */
+		onChange: (cb: (event: PhaseTimelineEvent) => void) => (() => void);
 	};
 	readonly wait: {
 		generationStarted: (options?: WaitOptions) => Promise<{
@@ -5915,6 +5970,10 @@ export declare class VibeClient {
 	get baseUrl(): string;
 	/**
 	 * Creates a new agent/app from a prompt and returns a BuildSession.
+	 *
+	 * By default, waits for all blueprint chunks before returning. Set
+	 * `waitForBlueprint: false` to return immediately after the start event,
+	 * with blueprint chunks streaming in the background.
 	 */
 	build(prompt: string, options?: BuildOptions): Promise<BuildSession>;
 	/** Connect to an existing agent/app by id. */

package/dist/index.js

@@ -292,6 +292,9 @@ class SessionStateStore {
   onChange(cb) {
     return this.emitter.on("change", ({ prev, next }) => cb(next, prev));
   }
+  onPhaseChange(cb) {
+    return this.emitter.on("phaseChange", cb);
+  }
   setConnection(state) {
     this.setState({ connection: state });
   }
@@ -406,7 +409,7 @@ class SessionStateStore {
         const m = msg;
         const phaseInfo = extractPhaseInfo(m);
         const phaseFiles = extractPhaseFiles(m);
-        const phases = this.updateOrAddPhase(phaseInfo, "validating", phaseFiles);
+        const phases = this.updateOrAddPhase(phaseInfo, "completed", phaseFiles);
         this.setState({
           phase: { status: "implemented", ...phaseInfo },
           phases
@@ -428,7 +431,7 @@ class SessionStateStore {
         const m = msg;
         const phaseInfo = extractPhaseInfo(m);
         const phaseFiles = extractPhaseFiles(m);
-        const phases = this.updateOrAddPhase(phaseInfo, "completed", phaseFiles);
+        const phases = this.updateOrAddPhase(phaseInfo, "validating", phaseFiles);
         this.setState({
           phase: { status: "validated", ...phaseInfo },
           phases
@@ -524,7 +527,7 @@ class SessionStateStore {
     const files = (phaseFiles ?? []).map((f) => ({
       path: f.path,
       purpose: f.purpose,
-      status: status === "completed" ? "completed" : "generating"
+      status: status === "completed" ? "completed" : "pending"
     }));
     if (existingIndex >= 0) {
       phases[existingIndex] = {
@@ -549,6 +552,38 @@ class SessionStateStore {
     const next = { ...prev, ...patch };
     this.state = next;
     this.emitter.emit("change", { prev, next });
+    if (patch.phases && patch.phases !== prev.phases) {
+      this.emitPhaseChanges(prev.phases, patch.phases);
+    }
+  }
+  emitPhaseChanges(prevPhases, nextPhases) {
+    for (const phase of nextPhases) {
+      const prevPhase = prevPhases.find((p) => p.id === phase.id);
+      if (!prevPhase) {
+        this.emitter.emit("phaseChange", {
+          type: "added",
+          phase,
+          allPhases: nextPhases
+        });
+      } else if (this.hasPhaseChanged(prevPhase, phase)) {
+        this.emitter.emit("phaseChange", {
+          type: "updated",
+          phase,
+          allPhases: nextPhases
+        });
+      }
+    }
+  }
+  hasPhaseChanged(prev, next) {
+    if (prev.status !== next.status)
+      return true;
+    if (prev.files.length !== next.files.length)
+      return true;
+    for (let i = 0;i < prev.files.length; i++) {
+      if (prev.files[i].status !== next.files[i].status)
+        return true;
+    }
+    return false;
   }
   clear() {
     this.state = INITIAL_STATE;
@@ -583,7 +618,7 @@ async function withTimeout(promise, ms, message = "Operation timed out") {
 // src/ws.ts
 var WS_RETRY_DEFAULTS = {
   enabled: true,
-  initialDelayMs: 1000,
+  initialDelayMs: 200,
   maxDelayMs: 30000,
   maxRetries: Infinity
 };
@@ -595,6 +630,7 @@ function createAgentConnection(getUrl, options = {}) {
   let closedByUser = false;
   let reconnectAttempts = 0;
   let reconnectTimer = null;
+  let hasConnectedBefore = false;
   const pendingSends = [];
   const maxPendingSends = 1000;
   function clearReconnectTimer() {
@@ -620,22 +656,34 @@ function createAgentConnection(getUrl, options = {}) {
       return;
     if (reconnectTimer)
       return;
-    const delayMs = computeBackoffMs(reconnectAttempts, retryCfg);
+    const delayMs = reconnectAttempts === 0 ? 0 : computeBackoffMs(reconnectAttempts, retryCfg);
     emitter.emit("ws:reconnecting", {
       attempt: reconnectAttempts + 1,
       delayMs,
       reason
     });
     reconnectAttempts += 1;
-    reconnectTimer = setTimeout(() => {
-      reconnectTimer = null;
-      connectNow();
-    }, delayMs);
+    if (delayMs === 0) {
+      reconnectTimer = setTimeout(() => {
+        reconnectTimer = null;
+        connectNow();
+      }, 0);
+    } else {
+      reconnectTimer = setTimeout(() => {
+        reconnectTimer = null;
+        connectNow();
+      }, delayMs);
+    }
   }
   function onOpen() {
+    const isReconnect = hasConnectedBefore;
+    hasConnectedBefore = true;
     isOpen = true;
     reconnectAttempts = 0;
     emitter.emit("ws:open", undefined);
+    if (isReconnect) {
+      emitter.emit("ws:reconnected", undefined);
+    }
     flushPendingSends();
   }
   function onClose(e) {
@@ -946,7 +994,8 @@ class BuildSession {
     completed: () => this.state.get().phases.filter((p) => p.status === "completed"),
     get: (id) => this.state.get().phases.find((p) => p.id === id),
     count: () => this.state.get().phases.length,
-    allCompleted: () => this.state.get().phases.length > 0 && this.state.get().phases.every((p) => p.status === "completed")
+    allCompleted: () => this.state.get().phases.length > 0 && this.state.get().phases.every((p) => p.status === "completed"),
+    onChange: (cb) => this.state.onPhaseChange(cb)
   };
   wait = {
     generationStarted: (options = {}) => this.waitForGenerationStarted(options),
@@ -969,7 +1018,7 @@ class BuildSession {
   async connect(options = {}) {
     if (this.connection)
       return this.connection;
-    const { autoRequestConversationState, credentials, ...connectionOptions } = options;
+    const { autoRequestConversationState, autoRequestPreview, credentials, ...connectionOptions } = options;
     const getUrl = async () => {
       const { ticket } = await this.init.httpClient.getWsTicket(this.agentId);
       const base = this.websocketUrl;
@@ -990,6 +1039,7 @@ class BuildSession {
     });
     const sessionCredentials = credentials ?? this.init.defaultCredentials;
     const shouldRequestConversationState = autoRequestConversationState ?? true;
+    const shouldRequestPreview = autoRequestPreview ?? (this.init.isExistingApp ?? false);
     this.connection.on("ws:open", () => {
       if (sessionCredentials) {
         this.connection?.send({
@@ -1000,6 +1050,14 @@ class BuildSession {
       if (shouldRequestConversationState) {
         this.connection?.send({ type: "get_conversation_state" });
       }
+      if (shouldRequestPreview) {
+        this.connection?.send({ type: "preview" });
+      }
+    });
+    this.connection.on("ws:reconnected", () => {
+      if (shouldRequestPreview) {
+        this.connection?.send({ type: "preview" });
+      }
     });
     return this.connection;
   }
@@ -1162,24 +1220,35 @@ class VibeClient {
     if (!resp.body) {
       throw new Error("Missing response body from /api/agent");
     }
-    let start = null;
-    for await (const obj of parseNdjsonStream(resp.body)) {
-      if (!start) {
-        start = obj;
-        continue;
-      }
-      const o = obj;
-      if (typeof o.chunk === "string") {
-        options.onBlueprintChunk?.(o.chunk);
-      }
-    }
-    if (!start) {
+    const iterator = parseNdjsonStream(resp.body)[Symbol.asyncIterator]();
+    const { value: start, done } = await iterator.next();
+    if (done || !start) {
       throw new Error("No start event received from /api/agent");
     }
     const session = new BuildSession(start, {
       httpClient: this.http,
       ...options.credentials ? { defaultCredentials: options.credentials } : {}
     });
+    const waitForBlueprint = options.waitForBlueprint ?? true;
+    const processChunks = async () => {
+      let result = await iterator.next();
+      while (!result.done) {
+        const obj = result.value;
+        if (typeof obj.chunk === "string") {
+          options.onBlueprintChunk?.(obj.chunk);
+        }
+        result = await iterator.next();
+      }
+    };
+    if (waitForBlueprint) {
+      await processChunks();
+    } else {
+      processChunks().catch((error) => {
+        const err = error instanceof Error ? error : new Error(String(error));
+        options.onBlueprintError?.(err);
+        session.close();
+      });
+    }
     if (options.autoConnect ?? true) {
       await session.connect();
       if (options.autoGenerate ?? true) {
@@ -1199,6 +1268,7 @@ class VibeClient {
     };
     return new BuildSession(start, {
       httpClient: this.http,
+      isExistingApp: true,
       ...options.credentials ? { defaultCredentials: options.credentials } : {}
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cf-vibesdk/sdk",
-	"version": "0.0.8",
+	"version": "0.1.0",
 	"type": "module",
 	"exports": {
 		".": {