Merge pull request #292 from cloudflare/main

Release: Main to build.cloudflare.dev

Author: AshishKumar4

CHANGELOG.md

@@ -1,5 +1,110 @@
 # Changelog
 
+## [1.4.0](https://github.com/cloudflare/vibesdk/compare/v1.3.0...v1.4.0) (2025-12-20)
+
+
+### Features
+
+* add blueprint parsing utilities and enhanced session state tracking to SDK ([96168d5](https://github.com/cloudflare/vibesdk/commit/96168d54ebf8352af9bfdf9113f04a3df5aaf90b))
+* add common pitfalls and dependency documentation to phase implementation prompt ([0184e5f](https://github.com/cloudflare/vibesdk/commit/0184e5fadf4f8c2a0f31d6e11853b7cd2115e5b1))
+* add concurrency control and cleanup for Claude review workflow ([b5a76da](https://github.com/cloudflare/vibesdk/commit/b5a76dae70febd9c624ab75f4f0e117c044c5c4e))
+* add dedicated AI changelog workflow and improve release-please gating ([4e97d5a](https://github.com/cloudflare/vibesdk/commit/4e97d5a8e1e85be02d04bf3c62a00d2ab8ff5f62))
+* add feature modules and capabilities discovery ([0534a95](https://github.com/cloudflare/vibesdk/commit/0534a955f40682cd0163ed315a4963cfde0cf1b4))
+* add HTTP retry logic with exponential backoff to SDK client ([b02025e](https://github.com/cloudflare/vibesdk/commit/b02025e050adc6c6c7fa324211743b63efe6df49))
+* add integration test controls and exclude from pre-commit hooks ([e68369b](https://github.com/cloudflare/vibesdk/commit/e68369b9e61b4eb7ad56b30d4c39c2b55d437fd2))
+* add missing environment variables to .prod.vars template generation ([7127cad](https://github.com/cloudflare/vibesdk/commit/7127cadd0c7a8b2b456c7e7bd79371af98f8d3b8))
+* add missing environment variables to deployment workflow and script ([965381c](https://github.com/cloudflare/vibesdk/commit/965381ca7e47bd138656cb50d47ecd32a388ff6f))
+* add new model definitions ([e73a089](https://github.com/cloudflare/vibesdk/commit/e73a08928021823068d5dc2ece0a97d303b30504))
+* add pre-deploy safety gate with automated code fixing ([611eb8e](https://github.com/cloudflare/vibesdk/commit/611eb8e5bb0cc3c9c3ea56efb7578a3d5117d177))
+* add query length validation with 20k character limit ([8927bf0](https://github.com/cloudflare/vibesdk/commit/8927bf01b48ff4357a1d2e46cb5cb518ef9cbde4))
+* add query length validation with 20k character limit ([715d21f](https://github.com/cloudflare/vibesdk/commit/715d21fca5a2ac04972d9b7eea600471b81663b9))
+* add release-live deployment workflow and vitest bun:test alias ([a71e382](https://github.com/cloudflare/vibesdk/commit/a71e3826bf011c90bdbd89d26a0ab3a8bd0edc7c))
+* add retry logic and blank screenshot detection for browser rendering ([c30a422](https://github.com/cloudflare/vibesdk/commit/c30a422fa606bac5480ba7bca8cc31178e08db6d))
+* add SDK documentation and usage example to main README ([3b11517](https://github.com/cloudflare/vibesdk/commit/3b11517310cd4fc5594cdab4caf1316ea7b4e9ce))
+* change the official preview domain to cloudflarepreviews.net ([516f92c](https://github.com/cloudflare/vibesdk/commit/516f92cbc5ac94024ae5a933cd3aa93b29b666fd))
+* client sdk + tests + docs ([46d7769](https://github.com/cloudflare/vibesdk/commit/46d7769bc12253a4240c5b447772f0391d8f28c3))
+* enable Agent SDK for all Claude Code Action workflows ([4aa6f5f](https://github.com/cloudflare/vibesdk/commit/4aa6f5f12ab2050930a759d44b1260d6af2103b8))
+* enhance CI/CD workflows with security and automation improvements ([d86377e](https://github.com/cloudflare/vibesdk/commit/d86377eebfe5d2086f9b9700ea241bec17ae5129))
+* enhance Claude review workflow with comment-based triggers and sticky comments ([9716c42](https://github.com/cloudflare/vibesdk/commit/9716c42988338e3026627483680777d9e91abbfb))
+* enhance Claude review workflow with improved PR description handling and streamlined review process ([6f6dc84](https://github.com/cloudflare/vibesdk/commit/6f6dc84c11e724f320e3ac2b6d6d8dc224361381))
+* gemini 3 flash ([6452622](https://github.com/cloudflare/vibesdk/commit/64526224e96e8284e345bdcc61cdf28d0c49658a))
+* improve phase generation and React render loop prevention prompts ([edc9deb](https://github.com/cloudflare/vibesdk/commit/edc9deb1e4d243dfb80118ddebcad0b6a50c8c16))
+* improve SDK error handling and resource cleanup ([17f1d4e](https://github.com/cloudflare/vibesdk/commit/17f1d4ed28487cd83da8ba3271c07ef65f30782b))
+* improve workflow metadata handling and cryptographic security ([5869e41](https://github.com/cloudflare/vibesdk/commit/5869e4123aeffe756b0e2b86597b83b4eade5ec3))
+* improve workflow reliability and add nightly branch support ([07d2d09](https://github.com/cloudflare/vibesdk/commit/07d2d09d1b65a5673e429f911ec6f770e4d4760d))
+* increase temperature and reasoning effort for blueprint ([f0ec7c9](https://github.com/cloudflare/vibesdk/commit/f0ec7c97c519c3c9c06fc54ca827324a90cc960a))
+* new zero knowledge vault implementation ([fd28396](https://github.com/cloudflare/vibesdk/commit/fd283966ef257178b4332a1c828638d1c3d77f47))
+* optimize phase context and reduce max phases to 10 ([0557bf7](https://github.com/cloudflare/vibesdk/commit/0557bf71c61ba6c7eb68ad07600ef87768366cbb))
+* optimize pre-commit hook with selective typecheck and related tests ([1cab335](https://github.com/cloudflare/vibesdk/commit/1cab3357291c91f631705a975d4786a5304ed58f))
+* phase implementation propmt rewrite - v78 prompt variant ([ffa547e](https://github.com/cloudflare/vibesdk/commit/ffa547e3e6fedc07c694052a2added4a810424b9))
+* refine agent model configurations and phase generation strategy ([69c8642](https://github.com/cloudflare/vibesdk/commit/69c86425590c108d7926a7c074ee2a830d5aa593))
+* replace CLI token authentication with SDK API key management ([30ba991](https://github.com/cloudflare/vibesdk/commit/30ba9918fc0eb176c65ff0ff0d4912a425413ecb))
+* some prompt improvements ([e136129](https://github.com/cloudflare/vibesdk/commit/e1361297a704e78e059bddcffeb5c3f3f3490782))
+* suppress AI Gateway token in CI and limit template deploy environment variables ([ee7a83f](https://github.com/cloudflare/vibesdk/commit/ee7a83ff1d1e11bbbf7607c4c7a74a75dbef29d1))
+* truncate exec command output to prevent token overflow ([2d05283](https://github.com/cloudflare/vibesdk/commit/2d0528363c98fc54c4e105e750eda20b8e55b414))
+
+
+### Bug Fixes
+
+* correct indentation in vault-context unlock error handler ([f908d31](https://github.com/cloudflare/vibesdk/commit/f908d31e0e3956675a9def25e74d1913dbb19b9c))
+* detect module-level JSX anti-pattern in safety gate ([37e5ef5](https://github.com/cloudflare/vibesdk/commit/37e5ef5edd6c48b075d8cd31b03b40b502a43d2b))
+* improve shell safety and variable handling in claude-reviews gating ([f656cf0](https://github.com/cloudflare/vibesdk/commit/f656cf07d0e1b9d33ea593733ca15b77a715452d))
+* improve shell safety and variable handling in claude-reviews gating ([31a1820](https://github.com/cloudflare/vibesdk/commit/31a1820c2c3cac6ce7d41401a13565ec2f91f08a))
+* improved process monitoring, failure detection and restarts ([ca7d309](https://github.com/cloudflare/vibesdk/commit/ca7d309405c4a750f344371caef6a7b95b0714d3))
+* prevent duplicate agent session creation and improve error handling in chat initialization ([40103ef](https://github.com/cloudflare/vibesdk/commit/40103ef67687d642b955172f6a841dd3abf6125d))
+* refine preview switching logic and fix code generation prompt ([a658282](https://github.com/cloudflare/vibesdk/commit/a658282b1ca6e364e5dbe374ca75fde12d18ab99))
+* remove redundant width/height styles from preview iframe ([f1efe5b](https://github.com/cloudflare/vibesdk/commit/f1efe5b1905cc59c6ee596183808add37f7a0e00))
+* resolve babel traverse import compatibility and disable phase parameter in safety gate ([c33a972](https://github.com/cloudflare/vibesdk/commit/c33a972a4aec6bee0ce056192a0bc75300db5d51))
+* stabilize legacy chats and preview rendering ([61421ed](https://github.com/cloudflare/vibesdk/commit/61421ed3575209356dc19828c7453b67a2d8d41f))
+* use safeFiles instead of finalFiles for phase implementation logging and broadcast ([849fdce](https://github.com/cloudflare/vibesdk/commit/849fdced2ad43dbf79be8d44d74f3524b2bb7f70))
+
+
+### Reverts
+
+* remove USE_AGENT_SDK flag from Claude Code Action workflows ([1380279](https://github.com/cloudflare/vibesdk/commit/13802798cf81fafa756d2d6c5030ea837db2fe00))
+
+## [1.3.0](https://github.com/cloudflare/vibesdk/compare/v1.2.0...v1.3.0) (2025-12-08)
+
+
+### Features
+
+* enforce template write-protection in simple code generator ([4f0dccf](https://github.com/cloudflare/vibesdk/commit/4f0dccf60661a6ae7ca09fd696270a0152316ea1))
+* latest packages updated ([e5496e0](https://github.com/cloudflare/vibesdk/commit/e5496e0cfd2923acc25d7e4f2265b4a0d7fd69f8))
+
+
+### Bug Fixes
+
+* filter protected files ([ff3a302](https://github.com/cloudflare/vibesdk/commit/ff3a302bf8fa3059156c4f10efc30c55aa6f0455))
+* variable name mismatch in simple code generation operation ([22b8f00](https://github.com/cloudflare/vibesdk/commit/22b8f0082ab0817be9fd9571c6d0806c49c1180a))
+
+## [1.2.0](https://github.com/cloudflare/vibesdk/compare/v1.1.0...v1.2.0) (2025-11-30)
+
+
+### Features
+
+* add agent-specific model constraints and refactor generation ([3f9ccf7](https://github.com/cloudflare/vibesdk/commit/3f9ccf7b3b1b137d6255493da14f8463ce8a66f3))
+* Cost optimizations via model configs and prompt improvements ([#247](https://github.com/cloudflare/vibesdk/issues/247)) ([2b3a901](https://github.com/cloudflare/vibesdk/commit/2b3a90149d336a1dc5aab6a7e4f999461cf147d3))
+* enhance changelog generation with detailed PR and commit data ([8950852](https://github.com/cloudflare/vibesdk/commit/89508523afada3f9522cdc19b994006b4e878a15))
+* improve template selection reliability and prompt clarity ([8ed1a08](https://github.com/cloudflare/vibesdk/commit/8ed1a0840b70f3e48a6245a89d4b4d468093ee97))
+* prompt tuning for shorter blueprints ([e9041f1](https://github.com/cloudflare/vibesdk/commit/e9041f1793bced58754a177c8a95e2609a5b56de))
+* rewrite process monitoring and error handling ([b0db701](https://github.com/cloudflare/vibesdk/commit/b0db701e82fad2d00820b7bd127b412017301cce))
+* upgraded to sandbox sdk version 0.5.2 ([9f9cc7a](https://github.com/cloudflare/vibesdk/commit/9f9cc7aa98be1373db0267b39cb7dd67d82d5dd6))
+
+
+### Bug Fixes
+
+* add additional ownership verification checks ([b74a645](https://github.com/cloudflare/vibesdk/commit/b74a645202937d0e8538265c9b7c6467f084655e))
+* added instructions for token creation ([3544038](https://github.com/cloudflare/vibesdk/commit/354403896f81573316f4ec5ec4fb1cae898fb255))
+* added instructions for token creation ([f7cc7ea](https://github.com/cloudflare/vibesdk/commit/f7cc7ea2bd243eefa176900e820b30b8a61e4c65))
+* added instructions for token creation ([ea3f110](https://github.com/cloudflare/vibesdk/commit/ea3f110fd9526da2978dd1064d377bf70f0c7c81))
+* better stale comment removal + correct YAML string escaping ([834cffa](https://github.com/cloudflare/vibesdk/commit/834cffa6968bc71513640e423a8f504f17d4ef9a))
+* cleanup chat.tsx for build ([670c8d6](https://github.com/cloudflare/vibesdk/commit/670c8d6c241d38335676440ecaa6225795ba6f2a))
+* don't wait for runtime errors if app not deployed ([0dd3e7e](https://github.com/cloudflare/vibesdk/commit/0dd3e7ef357a0193d6f8f5de9771306ab13754bd))
+* dont clear runtime errors on executeDeepDebug ([1eda73e](https://github.com/cloudflare/vibesdk/commit/1eda73ef5a57aa6203d9b7dac9d39bf160b2af00))
+* prevent race condition in code generation state ([188ba0d](https://github.com/cloudflare/vibesdk/commit/188ba0d1bdf7f30fd258275804e311921457d5e9))
+* typeScript features configurable to reduce memory ([d3f984c](https://github.com/cloudflare/vibesdk/commit/d3f984c3fd8e5ce4909f5849b97c3ecd3b900dd2))
+* unescape commit messages before git operations ([d51310b](https://github.com/cloudflare/vibesdk/commit/d51310b77723c87749a34c20b78a415054298eaa))
+
 ## [1.1.0](https://github.com/cloudflare/vibesdk/compare/v1.0.0...v1.1.0) (2025-11-04)
 
 

package.json

@@ -1,7 +1,7 @@
 {
 	"name": "vibesdk",
 	"private": true,
-	"version": "1.1.0",
+	"version": "1.4.0",
 	"type": "module",
 	"scripts": {
 		"setup": "tsx scripts/setup.ts",

sdk/package.json

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

sdk/src/blueprint.ts

@@ -0,0 +1,122 @@
+/**
+ * Utility for checking if a value is a plain object.
+ */
+export function isRecord(v: unknown): v is Record<string, unknown> {
+	return Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+}
+
+/**
+ * Blueprint structure as streamed from the agent.
+ */
+export type Blueprint = {
+	title?: string;
+	projectName?: string;
+	description?: string;
+	detailedDescription?: string;
+	frameworks?: string[];
+	views?: Array<{ name: string; description: string }>;
+	plan?: string[];
+	implementationRoadmap?: Array<{ phase: string; description: string }>;
+};
+
+/**
+ * Converts a Blueprint object to readable Markdown.
+ */
+export function blueprintToMarkdown(bp: Blueprint): string {
+	const lines: string[] = [];
+	const title = bp.title ?? bp.projectName ?? 'Blueprint';
+	lines.push(`# ${title}`);
+	if (bp.description) {
+		lines.push('');
+		lines.push(bp.description);
+	}
+	if (bp.frameworks?.length) {
+		lines.push('');
+		lines.push('## Frameworks');
+		for (const f of bp.frameworks) lines.push(`- ${f}`);
+	}
+	if (bp.detailedDescription) {
+		lines.push('');
+		lines.push('## Details');
+		lines.push(bp.detailedDescription);
+	}
+	if (bp.views?.length) {
+		lines.push('');
+		lines.push('## Views');
+		for (const v of bp.views) lines.push(`- **${v.name}**: ${v.description}`);
+	}
+	if (bp.plan?.length) {
+		lines.push('');
+		lines.push('## Plan');
+		bp.plan.forEach((s, idx) => lines.push(`${idx + 1}. ${s}`));
+	}
+	if (bp.implementationRoadmap?.length) {
+		lines.push('');
+		lines.push('## Roadmap');
+		for (const p of bp.implementationRoadmap) lines.push(`- **${p.phase}**: ${p.description}`);
+	}
+	return lines.join('\n');
+}
+
+function extractJsonStringField(raw: string, key: string): string | null {
+	const re = new RegExp(`"${key}"\\s*:\\s*"([^"\\n\\r]*)"`);
+	const m = re.exec(raw);
+	return m?.[1] ?? null;
+}
+
+/**
+ * Parses streaming blueprint chunks (JSON or Markdown) into Markdown.
+ * Handles partial JSON gracefully by extracting available fields.
+ */
+export class BlueprintStreamParser {
+	private buffer = '';
+
+	/**
+	 * Appends a chunk and returns the current Markdown representation.
+	 */
+	append(chunk: string): string {
+		this.buffer += chunk;
+		return this.toMarkdown();
+	}
+
+	/**
+	 * Returns the current Markdown representation of the buffer.
+	 */
+	toMarkdown(): string {
+		const startsLikeJson = /^\s*[\[{]/.test(this.buffer);
+		if (!startsLikeJson) {
+			return this.buffer;
+		}
+
+		try {
+			const parsed = JSON.parse(this.buffer) as unknown;
+			if (isRecord(parsed)) {
+				return blueprintToMarkdown(parsed as Blueprint);
+			}
+		} catch {
+			// Partial JSON: extract available fields
+		}
+
+		const title =
+			extractJsonStringField(this.buffer, 'title') ??
+			extractJsonStringField(this.buffer, 'projectName') ??
+			'Blueprint';
+		const desc = extractJsonStringField(this.buffer, 'description');
+		const lines = [`# ${title}`, '', desc ? desc : '*Generating blueprint...*'];
+		return lines.join('\n');
+	}
+
+	/**
+	 * Returns the raw buffer contents.
+	 */
+	getRaw(): string {
+		return this.buffer;
+	}
+
+	/**
+	 * Clears the buffer.
+	 */
+	clear(): void {
+		this.buffer = '';
+	}
+}

sdk/src/http.ts

@@ -1,4 +1,5 @@
 import type { VibeClientOptions } from './types';
+import { normalizeRetryConfig, computeBackoffMs, sleep, type NormalizedRetryConfig } from './retry';
 
 type ExchangeApiKeyData = {
 	accessToken: string;
@@ -12,10 +13,24 @@ type ApiResponse<T> =
 	| { success: true; data: T; message?: string }
 	| { success: false; error: { message: string }; message?: string };
 
+const HTTP_RETRY_DEFAULTS: NormalizedRetryConfig = {
+	enabled: true,
+	initialDelayMs: 1_000,
+	maxDelayMs: 10_000,
+	maxRetries: 3,
+};
+
+function isRetryableStatus(status: number): boolean {
+	return status >= 500 && status < 600;
+}
+
 export class HttpClient {
 	private cachedAccessToken: { token: string; expiresAtMs: number } | null = null;
+	private retryCfg: NormalizedRetryConfig;
 
-	constructor(private opts: VibeClientOptions) {}
+	constructor(private opts: VibeClientOptions) {
+		this.retryCfg = normalizeRetryConfig(opts.retry, HTTP_RETRY_DEFAULTS);
+	}
 
 	get baseUrl(): string {
 		return this.opts.baseUrl.replace(/\/$/, '');
@@ -82,21 +97,65 @@ export class HttpClient {
 
 	async fetchJson<T>(path: string, init?: RequestInit): Promise<T> {
 		const url = `${this.baseUrl}${path}`;
-		const resp = await this.fetchFn(url, init);
-		if (!resp.ok) {
-			const text = (await resp.text().catch(() => '')).slice(0, 1000);
-			throw new Error(`HTTP ${resp.status} for ${path}: ${text || resp.statusText}`);
+		let lastError: Error | null = 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()) as T;
+			} 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()) as T;
+
+		throw lastError ?? new Error(`Failed after ${this.retryCfg.maxRetries} retries`);
 	}
 
 	async fetchRaw(path: string, init?: RequestInit): Promise<Response> {
 		const url = `${this.baseUrl}${path}`;
-		const resp = await this.fetchFn(url, init);
-		if (!resp.ok) {
-			const text = (await resp.text().catch(() => '')).slice(0, 1000);
-			throw new Error(`HTTP ${resp.status} for ${path}: ${text || resp.statusText}`);
+		let lastError: Error | null = 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`);
 	}
 }

sdk/src/index.ts

@@ -5,6 +5,11 @@ export { BuildSession } from './session';
 export { WorkspaceStore } from './workspace';
 export { SessionStateStore } from './state';
 
+export { isRecord, blueprintToMarkdown, BlueprintStreamParser } from './blueprint';
+export type { Blueprint } from './blueprint';
+
+export { withTimeout, TimeoutError } from './utils';
+
 export type {
 	AgentConnection,
 	AgentConnectionOptions,
@@ -29,7 +34,7 @@ export type {
 	WaitOptions,
 } from './types';
 
-export type { SessionState } from './state';
+export type { SessionState, ConnectionState, GenerationState, PhaseState } from './state';
 
 export type {
 	AgentState,