@cf-vibesdk/sdk 0.0.7 → 0.0.9

package/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,71 @@ 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');
+
+// 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:
+
+```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 +299,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 +407,24 @@ All types are exported:
 
 ```ts
 import type {
+  // Client & Session
   VibeClientOptions,
   BuildOptions,
   BuildSession,
   SessionState,
+  SessionFiles,
+  SessionPhases,
+  
+  // Phase Timeline
+  PhaseInfo,
+  PhaseFile,
+  PhaseStatus,
+  PhaseFileStatus,
+  PhaseEventType,
+  PhaseTimelineEvent,
+  PhaseTimelineChangeType,
+  
+  // API
   ApiResponse,
   AppDetails,
   Credentials,

package/dist/index.d.ts

@@ -5568,6 +5568,8 @@ export type AgentEventMap = {
 	error: {
 		error: string;
 	};
+	/** Emitted when the phase timeline changes (phase added or updated). */
+	phases: PhaseTimelineEvent;
 };
 /**
  * URL provider for WebSocket connections.
@@ -5613,6 +5615,62 @@ export type PhaseEventType = "phase_generating" | "phase_generated" | "phase_imp
 export type WaitForPhaseOptions = WaitOptions & {
 	type: PhaseEventType;
 };
+/**
+ * Status of a file within a phase.
+ */
+export type PhaseFileStatus = "pending" | "generating" | "completed" | "cancelled";
+/**
+ * A file concept within a phase, with its generation status.
+ * Extends platform's FileConceptType with status tracking.
+ */
+export type PhaseFile = Pick<FileConceptType, "path" | "purpose"> & {
+	status: PhaseFileStatus;
+};
+/**
+ * Status of a phase in the timeline.
+ */
+export type PhaseStatus = "pending" | "generating" | "implementing" | "validating" | "completed" | "cancelled";
+/**
+ * A phase in the build timeline with its files and status.
+ * Extends platform's PhaseConceptType with SDK-specific fields.
+ */
+export type PhaseInfo = Pick<PhaseConceptType, "name" | "description"> & {
+	/** Unique identifier for this phase (e.g., "phase-0", "phase-1"). */
+	id: string;
+	/** Current status of the phase. */
+	status: PhaseStatus;
+	/** Files in this phase with their generation status. */
+	files: PhaseFile[];
+};
+/**
+ * High-level API for accessing phase timeline data.
+ */
+export type SessionPhases = {
+	/** Get all phases in the timeline. */
+	list: () => PhaseInfo[];
+	/** Get the currently active phase (first non-completed phase), or undefined. */
+	current: () => PhaseInfo | undefined;
+	/** Get all completed phases. */
+	completed: () => PhaseInfo[];
+	/** Get a phase by its id (e.g., "phase-0"). */
+	get: (id: string) => PhaseInfo | undefined;
+	/** Get the total count of phases. */
+	count: () => number;
+	/** 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";
@@ -5697,15 +5755,48 @@ export type SessionState = {
 	preview: PreviewDeploymentState;
 	cloudflare: CloudflareDeploymentState;
 	lastError?: string;
+	/** Full phase timeline with status and files for each phase. */
+	phases: PhaseInfo[];
+	/** Behavior type of the agent (phasic or agentic). */
+	behaviorType?: BehaviorType$1;
+	/** Project type (app, workflow, presentation, general). */
+	projectType?: ProjectType$1;
+	/** Original user query that started this build. */
+	query?: string;
+	/** Whether the agent should be actively generating. */
+	shouldBeGenerating?: boolean;
+	/** Project name from the blueprint. */
+	projectName?: string;
 };
 export declare class SessionStateStore {
 	private state;
 	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;
+	/**
+	 * Update the status of a file in the phase timeline.
+	 */
+	private updateFileStatus;
+	/**
+	 * Update an existing phase or add a new one to the timeline.
+	 */
+	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 = {
@@ -5775,6 +5866,30 @@ export declare class BuildSession {
 	readonly workspace: WorkspaceStore;
 	readonly state: SessionStateStore;
 	readonly files: SessionFiles;
+	/**
+	 * 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[];
+		/** Get the currently active phase (first non-completed phase), or undefined. */
+		current: () => PhaseInfo | undefined;
+		/** Get all completed phases. */
+		completed: () => PhaseInfo[];
+		/** Get a phase by its id (e.g., "phase-0"). */
+		get: (id: string) => PhaseInfo | undefined;
+		/** Get the total count of phases. */
+		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<{
 			type: "generation_started";

package/dist/index.js

@@ -227,7 +227,8 @@ var INITIAL_STATE = {
   generation: { status: "idle" },
   phase: { status: "idle" },
   preview: { status: "idle" },
-  cloudflare: { status: "idle" }
+  cloudflare: { status: "idle" },
+  phases: []
 };
 function extractPhaseInfo(msg) {
   const phase = msg?.phase;
@@ -236,6 +237,51 @@ function extractPhaseInfo(msg) {
     description: phase?.description
   };
 }
+function extractPhaseFiles(msg) {
+  const phase = msg?.phase;
+  return phase?.files;
+}
+function isPhasicState(state) {
+  return state.behaviorType === "phasic" && "generatedPhases" in state;
+}
+function buildPhaseTimelineFromState(state, generatedFilesMap) {
+  if (!isPhasicState(state))
+    return [];
+  const isActivelyGenerating = state.shouldBeGenerating === true;
+  return state.generatedPhases.map((phase, index) => {
+    let status;
+    if (phase.completed) {
+      status = "completed";
+    } else if (!isActivelyGenerating) {
+      status = "cancelled";
+    } else {
+      status = "generating";
+    }
+    const files = phase.files.map((f) => {
+      const fileExists = f.path in generatedFilesMap;
+      let fileStatus;
+      if (fileExists) {
+        fileStatus = "completed";
+      } else if (!isActivelyGenerating) {
+        fileStatus = "cancelled";
+      } else {
+        fileStatus = "pending";
+      }
+      return {
+        path: f.path,
+        purpose: f.purpose,
+        status: fileStatus
+      };
+    });
+    return {
+      id: `phase-${index}`,
+      name: phase.name,
+      description: phase.description,
+      status,
+      files
+    };
+  });
+}
 
 class SessionStateStore {
   state = INITIAL_STATE;
@@ -246,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 });
   }
@@ -303,47 +352,90 @@ class SessionStateStore {
       }
       case "file_generating": {
         const m = msg;
-        this.setState({ currentFile: m.filePath });
+        const phasesWithGenerating = this.updateFileStatus(m.filePath, "generating");
+        this.setState({ currentFile: m.filePath, phases: phasesWithGenerating });
         break;
       }
       case "file_generated": {
+        const m = msg;
+        const filePath = m.file?.filePath;
         const prev = this.state.generation;
+        const phasesWithCompleted = filePath ? this.updateFileStatus(filePath, "completed") : this.state.phases;
         if (prev.status === "running" || prev.status === "stopped") {
           this.setState({
             generation: { ...prev, filesGenerated: prev.filesGenerated + 1 },
-            currentFile: undefined
+            currentFile: undefined,
+            phases: phasesWithCompleted
           });
+        } else {
+          this.setState({ phases: phasesWithCompleted, currentFile: undefined });
         }
         break;
       }
       case "phase_generating": {
         const m = msg;
-        this.setState({ phase: { status: "generating", ...extractPhaseInfo(m) } });
+        const phaseInfo = extractPhaseInfo(m);
+        const phaseFiles = extractPhaseFiles(m);
+        const phases = this.updateOrAddPhase(phaseInfo, "generating", phaseFiles);
+        this.setState({
+          phase: { status: "generating", ...phaseInfo },
+          phases
+        });
         break;
       }
       case "phase_generated": {
         const m = msg;
-        this.setState({ phase: { status: "generated", ...extractPhaseInfo(m) } });
+        const phaseInfo = extractPhaseInfo(m);
+        const phaseFiles = extractPhaseFiles(m);
+        const phases = this.updateOrAddPhase(phaseInfo, "implementing", phaseFiles);
+        this.setState({
+          phase: { status: "generated", ...phaseInfo },
+          phases
+        });
         break;
       }
       case "phase_implementing": {
         const m = msg;
-        this.setState({ phase: { status: "implementing", ...extractPhaseInfo(m) } });
+        const phaseInfo = extractPhaseInfo(m);
+        const phaseFiles = extractPhaseFiles(m);
+        const phases = this.updateOrAddPhase(phaseInfo, "implementing", phaseFiles);
+        this.setState({
+          phase: { status: "implementing", ...phaseInfo },
+          phases
+        });
         break;
       }
       case "phase_implemented": {
         const m = msg;
-        this.setState({ phase: { status: "implemented", ...extractPhaseInfo(m) } });
+        const phaseInfo = extractPhaseInfo(m);
+        const phaseFiles = extractPhaseFiles(m);
+        const phases = this.updateOrAddPhase(phaseInfo, "validating", phaseFiles);
+        this.setState({
+          phase: { status: "implemented", ...phaseInfo },
+          phases
+        });
         break;
       }
       case "phase_validating": {
         const m = msg;
-        this.setState({ phase: { status: "validating", ...extractPhaseInfo(m) } });
+        const phaseInfo = extractPhaseInfo(m);
+        const phaseFiles = extractPhaseFiles(m);
+        const phases = this.updateOrAddPhase(phaseInfo, "validating", phaseFiles);
+        this.setState({
+          phase: { status: "validating", ...phaseInfo },
+          phases
+        });
         break;
       }
       case "phase_validated": {
         const m = msg;
-        this.setState({ phase: { status: "validated", ...extractPhaseInfo(m) } });
+        const phaseInfo = extractPhaseInfo(m);
+        const phaseFiles = extractPhaseFiles(m);
+        const phases = this.updateOrAddPhase(phaseInfo, "completed", phaseFiles);
+        this.setState({
+          phase: { status: "validated", ...phaseInfo },
+          phases
+        });
         break;
       }
       case "deployment_started": {
@@ -394,9 +486,24 @@ class SessionStateStore {
       }
       case "agent_connected": {
         const m = msg;
+        const agentState = m.state;
         const previewUrl = m.previewUrl;
-        if (previewUrl)
-          this.setState({ previewUrl });
+        const phases = buildPhaseTimelineFromState(agentState, agentState.generatedFilesMap ?? {});
+        let generation = this.state.generation;
+        if (agentState.shouldBeGenerating) {
+          const filesGenerated = Object.keys(agentState.generatedFilesMap ?? {}).length;
+          generation = { status: "running", filesGenerated };
+        }
+        this.setState({
+          previewUrl,
+          phases,
+          generation,
+          behaviorType: agentState.behaviorType,
+          projectType: agentState.projectType,
+          query: agentState.query,
+          shouldBeGenerating: agentState.shouldBeGenerating,
+          projectName: agentState.projectName
+        });
         break;
       }
       case "error": {
@@ -408,11 +515,75 @@ class SessionStateStore {
         break;
     }
   }
+  updateFileStatus(filePath, status) {
+    return this.state.phases.map((phase) => ({
+      ...phase,
+      files: phase.files.map((f) => f.path === filePath ? { ...f, status } : f)
+    }));
+  }
+  updateOrAddPhase(phaseInfo, status, phaseFiles) {
+    const phases = [...this.state.phases];
+    const existingIndex = phases.findIndex((p) => p.name === phaseInfo.name);
+    const files = (phaseFiles ?? []).map((f) => ({
+      path: f.path,
+      purpose: f.purpose,
+      status: status === "completed" ? "completed" : "pending"
+    }));
+    if (existingIndex >= 0) {
+      phases[existingIndex] = {
+        ...phases[existingIndex],
+        status,
+        description: phaseInfo.description ?? phases[existingIndex].description,
+        files: files.length > 0 ? files : phases[existingIndex].files
+      };
+    } else if (phaseInfo.name) {
+      phases.push({
+        id: `phase-${phases.length}`,
+        name: phaseInfo.name,
+        description: phaseInfo.description ?? "",
+        status,
+        files
+      });
+    }
+    return phases;
+  }
   setState(patch) {
     const prev = this.state;
     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;
@@ -804,6 +975,15 @@ class BuildSession {
     snapshot: () => this.workspace.snapshot(),
     tree: () => buildFileTree(this.workspace.paths())
   };
+  phases = {
+    list: () => this.state.get().phases,
+    current: () => this.state.get().phases.find((p) => p.status !== "completed" && p.status !== "cancelled"),
+    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"),
+    onChange: (cb) => this.state.onPhaseChange(cb)
+  };
   wait = {
     generationStarted: (options = {}) => this.waitForGenerationStarted(options),
     generationComplete: (options = {}) => this.waitForGenerationComplete(options),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cf-vibesdk/sdk",
-	"version": "0.0.7",
+	"version": "0.0.9",
 	"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",