feat: implement phase timeline management and state tracking in SDK

Author: AshishKumar4

sdk/README.md

@@ -96,13 +96,21 @@ const session = await client.build('Build a weather dashboard', {
 
 ### `client.connect(agentId)`
 
-Connect to an existing app session.
+Connect to an existing app session. State is automatically restored from the agent, including:
+- Phase timeline with completion status
+- Generated files
+- Agent metadata (query, projectName, behaviorType, etc.)
 
 ```ts
 const session = await client.connect('agent-id-here', {
   credentials: { ... },  // Optional
 });
 await session.connect();
+
+// State is now seeded from the agent
+console.log('Original query:', session.state.get().query);
+console.log('Phases:', session.phases.list());
+console.log('Files:', session.files.listPaths());
 ```
 
 ## App Management
@@ -215,6 +223,53 @@ const snapshot = session.files.snapshot();      // { 'src/App.tsx': '...', ... }
 const tree = session.files.tree();              // Nested file tree structure
 ```
 
+### Phase Timeline
+
+Access the full phase timeline for phasic builds. The timeline is automatically seeded when connecting to an existing agent and updated as phases progress.
+
+```ts
+// Get all phases
+const phases = session.phases.list();
+// [{ id: 'phase-0', name: 'Core Setup', status: 'completed', files: [...] }, ...]
+
+// Get current active phase
+const current = session.phases.current();
+if (current) {
+  console.log(`Working on: ${current.name}`);
+  console.log(`Status: ${current.status}`);  // 'generating' | 'implementing' | 'validating'
+}
+
+// Get completed phases
+const done = session.phases.completed();
+console.log(`Progress: ${done.length}/${session.phases.count()}`);
+
+// Check if all phases are done
+if (session.phases.allCompleted()) {
+  console.log('Build complete!');
+}
+
+// Get phase by ID
+const phase = session.phases.get('phase-0');
+```
+
+Each phase contains:
+
+```ts
+type PhaseInfo = {
+  id: string;           // 'phase-0', 'phase-1', etc.
+  name: string;         // 'Core Setup', 'Authentication', etc.
+  description: string;  // What the phase accomplishes
+  status: PhaseStatus;  // 'pending' | 'generating' | 'implementing' | 'validating' | 'completed' | 'cancelled'
+  files: PhaseFile[];   // Files in this phase
+};
+
+type PhaseFile = {
+  path: string;         // 'src/App.tsx'
+  purpose: string;      // 'Main application component'
+  status: PhaseFileStatus;  // 'pending' | 'generating' | 'completed' | 'cancelled'
+};
+```
+
 ### State
 
 ```ts
@@ -226,6 +281,16 @@ console.log(state.phase);       // { status: 'idle' | 'generating' | ... }
 console.log(state.preview);     // Preview deployment state
 console.log(state.cloudflare);  // Cloudflare deployment state
 
+// Phase timeline (array of all phases)
+console.log(state.phases);      // [{ id, name, status, files }, ...]
+
+// Agent metadata (seeded from agent_connected)
+console.log(state.behaviorType);      // 'phasic' | 'agentic'
+console.log(state.projectType);       // 'app' | 'workflow' | etc.
+console.log(state.query);             // Original user prompt
+console.log(state.projectName);       // Project name from blueprint
+console.log(state.shouldBeGenerating); // Whether agent is actively generating
+
 // Subscribe to changes
 session.state.onChange((next, prev) => {
   console.log('State changed:', next);
@@ -324,10 +389,22 @@ All types are exported:
 
 ```ts
 import type {
+  // Client & Session
   VibeClientOptions,
   BuildOptions,
   BuildSession,
   SessionState,
+  SessionFiles,
+  SessionPhases,
+  
+  // Phase Timeline
+  PhaseInfo,
+  PhaseFile,
+  PhaseStatus,
+  PhaseFileStatus,
+  PhaseEventType,
+  
+  // API
   ApiResponse,
   AppDetails,
   Credentials,

sdk/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cf-vibesdk/sdk",
-	"version": "0.0.7",
+	"version": "0.0.8",
 	"type": "module",
 	"exports": {
 		".": {
@@ -22,7 +22,8 @@
 		"bundle-types": "dts-bundle-generator --export-referenced-types false --no-check --project ./tsconfig.protocol.json -o ./dist/index.d.ts ./src/index.ts && bun run scripts/expand-drizzle-types.ts",
 		"typecheck": "tsc -p ./tsconfig.json --noEmit",
 		"test": "bun test test/*.test.ts",
-		"test:integration": "bun test --timeout 600000 test/integration/*.test.ts"
+		"test:integration": "bun test --timeout 600000 test/integration/*.test.ts",
+		"package": "bun run typecheck && bun run test && bun run build && bun run bundle-types"
 	},
 	"devDependencies": {
 		"@cloudflare/workers-types": "^4.20241218.0",

sdk/src/index.ts

@@ -34,10 +34,15 @@ export type {
 	GitCloneTokenData,
 	PaginationInfo,
 	PhaseEventType,
+	PhaseFile,
+	PhaseFileStatus,
+	PhaseInfo,
+	PhaseStatus,
 	ProjectType,
 	PublicAppsQuery,
 	SessionDeployable,
 	SessionFiles,
+	SessionPhases,
 	ToggleResult,
 	UrlProvider,
 	VibeClientOptions,

sdk/src/protocol.ts

@@ -15,7 +15,7 @@ export type {
 
 export type { AgentState } from '../../worker/agents/core/state';
 export type { BehaviorType, ProjectType } from '../../worker/agents/core/types';
-export type { FileOutputType } from '../../worker/agents/schemas';
+export type { FileOutputType, FileConceptType, PhaseConceptType } from '../../worker/agents/schemas';
 export type { TemplateDetails } from '../../worker/services/sandbox/sandboxTypes';
 
 export type {

sdk/src/session.ts

@@ -8,6 +8,7 @@ import type {
 	FileTreeNode,
 	ImageAttachment,
 	PhaseEventType,
+	PhaseInfo,
 	ProjectType,
 	SessionDeployable,
 	SessionFiles,
@@ -101,6 +102,35 @@ export class BuildSession {
 		tree: () => buildFileTree(this.workspace.paths()),
 	};
 
+	/**
+	 * High-level API for accessing the phase timeline.
+	 * Phases are seeded from agent_connected and updated on phase events.
+	 */
+	readonly phases = {
+		/** Get all phases in the timeline. */
+		list: (): PhaseInfo[] => this.state.get().phases,
+
+		/** Get the currently active phase (first non-completed phase), or undefined. */
+		current: (): PhaseInfo | undefined =>
+			this.state.get().phases.find((p) => p.status !== 'completed' && p.status !== 'cancelled'),
+
+		/** Get all completed phases. */
+		completed: (): PhaseInfo[] =>
+			this.state.get().phases.filter((p) => p.status === 'completed'),
+
+		/** Get a phase by its id (e.g., "phase-0"). */
+		get: (id: string): PhaseInfo | undefined =>
+			this.state.get().phases.find((p) => p.id === id),
+
+		/** Get the total count of phases. */
+		count: (): number => this.state.get().phases.length,
+
+		/** Check if all phases are completed. */
+		allCompleted: (): boolean =>
+			this.state.get().phases.length > 0 &&
+			this.state.get().phases.every((p) => p.status === 'completed'),
+	};
+
 	readonly wait = {
 		generationStarted: (options: WaitOptions = {}) => this.waitForGenerationStarted(options),
 		generationComplete: (options: WaitOptions = {}) => this.waitForGenerationComplete(options),