feat: add phase timeline change subscription and event handling

Author: AshishKumar4

sdk/README.md

@@ -250,6 +250,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:
@@ -403,6 +421,8 @@ import type {
   PhaseStatus,
   PhaseFileStatus,
   PhaseEventType,
+  PhaseTimelineEvent,
+  PhaseTimelineChangeType,
 
   // API
   ApiResponse,

sdk/package.json

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

sdk/src/index.ts

@@ -38,6 +38,8 @@ export type {
 	PhaseFileStatus,
 	PhaseInfo,
 	PhaseStatus,
+	PhaseTimelineChangeType,
+	PhaseTimelineEvent,
 	ProjectType,
 	PublicAppsQuery,
 	SessionDeployable,

sdk/src/session.ts

@@ -9,6 +9,7 @@ import type {
 	ImageAttachment,
 	PhaseEventType,
 	PhaseInfo,
+	PhaseTimelineEvent,
 	ProjectType,
 	SessionDeployable,
 	SessionFiles,
@@ -129,6 +130,14 @@ export class BuildSession {
 		allCompleted: (): boolean =>
 			this.state.get().phases.length > 0 &&
 			this.state.get().phases.every((p) => p.status === 'completed'),
+
+		/**
+		 * 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) =>
+			this.state.onPhaseChange(cb),
 	};
 
 	readonly wait = {

sdk/src/state.ts

@@ -1,5 +1,5 @@
 import { TypedEmitter } from './emitter';
-import type { AgentWsServerMessage, WsMessageOf, PhaseInfo, PhaseFile, BehaviorType, ProjectType } from './types';
+import type { AgentWsServerMessage, WsMessageOf, PhaseInfo, PhaseFile, BehaviorType, ProjectType, PhaseTimelineEvent, PhaseTimelineChangeType } from './types';
 import type { AgentState } from './protocol';
 
 export type ConnectionState = 'disconnected' | 'connecting' | 'connected';
@@ -78,6 +78,7 @@ export type SessionState = {
 
 type SessionStateEvents = {
 	change: { prev: SessionState; next: SessionState };
+	phaseChange: PhaseTimelineEvent;
 };
 
 const INITIAL_STATE: SessionState = {
@@ -169,6 +170,14 @@ export class SessionStateStore {
 		return this.emitter.on('change', ({ prev, next }) => cb(next, prev));
 	}
 
+	/**
+	 * 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 {
+		return this.emitter.on('phaseChange', cb);
+	}
+
 	setConnection(state: ConnectionState): void {
 		this.setState({ connection: state });
 	}
@@ -451,7 +460,7 @@ export class SessionStateStore {
 		const files: PhaseFile[] = (phaseFiles ?? []).map((f) => ({
 			path: f.path,
 			purpose: f.purpose,
-			status: status === 'completed' ? 'completed' : 'generating',
+			status: status === 'completed' ? 'completed' : 'pending',
 		}));
 
 		if (existingIndex >= 0) {
@@ -481,6 +490,48 @@ export class SessionStateStore {
 		const next: SessionState = { ...prev, ...patch };
 		this.state = next;
 		this.emitter.emit('change', { prev, next });
+
+		// Emit phase change events if phases array changed
+		if (patch.phases && patch.phases !== prev.phases) {
+			this.emitPhaseChanges(prev.phases, patch.phases);
+		}
+	}
+
+	/**
+	 * Compare old and new phases arrays and emit change events.
+	 */
+	private emitPhaseChanges(prevPhases: PhaseInfo[], nextPhases: PhaseInfo[]): void {
+		// Check for new phases (added)
+		for (const phase of nextPhases) {
+			const prevPhase = prevPhases.find((p) => p.id === phase.id);
+			if (!prevPhase) {
+				// New phase added
+				this.emitter.emit('phaseChange', {
+					type: 'added',
+					phase,
+					allPhases: nextPhases,
+				});
+			} else if (this.hasPhaseChanged(prevPhase, phase)) {
+				// Existing phase updated
+				this.emitter.emit('phaseChange', {
+					type: 'updated',
+					phase,
+					allPhases: nextPhases,
+				});
+			}
+		}
+	}
+
+	/**
+	 * Check if a phase has meaningfully changed (status or file statuses).
+	 */
+	private hasPhaseChanged(prev: PhaseInfo, next: PhaseInfo): boolean {
+		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(): void {

sdk/src/types.ts

@@ -186,6 +186,9 @@ export type AgentEventMap = {
 		| 'cloudflare_deployment_error'
 	>;
 	error: { error: string };
+
+	/** Emitted when the phase timeline changes (phase added or updated). */
+	phases: PhaseTimelineEvent;
 };
 
 // ============================================================================
@@ -306,6 +309,20 @@ export type SessionPhases = {
 	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';