feat(gcp-cloud-run): live chunk-level render progress via the step-entries API

docs/packages/gcp-cloud-run.mdx

@@ -98,6 +98,8 @@ console.log(progress.status, progress.outputFile, progress.costs.displayCost);
 
 Pass `projectDir` for one-shot uploads, or call `deploySite()` separately and reuse the returned site handle across many renders.
 
+While the execution is running, `getRenderProgress` reads the Cloud Workflows **step-entries API** to report live chunk-level progress — `overallProgress` follows the same 10% plan + 80% chunks + 10% assemble split as the AWS adapter, and `chunksCompleted` / `totalChunks` expose the raw counts. The read is best-effort: if the caller lacks `workflowexecutions.stepEntries.list` (included in `roles/workflows.viewer`) the snapshot degrades to coarse `overallProgress = 0` instead of failing. Pass `midFlightProgress: false` to skip the extra API call per poll. Exact frame totals and costs still come from the accumulated result on success.
+
 ## Related Guides
 
 <CardGroup cols={2}>

packages/cli/src/commands/cloudrun.ts

@@ -538,7 +538,15 @@ async function runRender(args: Record<string, unknown>): Promise<void> {
   while (progress.status === "running") {
     await new Promise((r) => setTimeout(r, intervalMs));
     progress = await getRenderProgress({ executionName: handle.executionName });
-    if (!args.json) process.stdout.write(`\r  status=${progress.status} `);
+    if (!args.json) {
+      const chunks =
+        progress.totalChunks != null
+          ? ` chunks=${progress.chunksCompleted}/${progress.totalChunks}`
+          : "";
+      process.stdout.write(
+        `\r  status=${progress.status} progress=${(progress.overallProgress * 100).toFixed(0)}%${chunks} `,
+      );
+    }
   }
   if (!args.json) process.stdout.write("\n");
   if (args.json) {
@@ -570,6 +578,8 @@ async function runProgress(args: Record<string, unknown>): Promise<void> {
     return;
   }
   console.log(`status=${progress.status} progress=${(progress.overallProgress * 100).toFixed(0)}%`);
+  if (progress.totalChunks != null)
+    console.log(`chunks=${progress.chunksCompleted}/${progress.totalChunks}`);
   if (progress.totalFrames)
     console.log(`frames=${progress.framesRendered}/${progress.totalFrames}`);
   if (progress.outputFile) console.log(`output=${progress.outputFile.gcsUri}`);

packages/gcp-cloud-run/package.json

@@ -45,6 +45,7 @@
     "@google-cloud/workflows": "^4.2.0",
     "@hono/node-server": "^1.13.0",
     "@hyperframes/producer": "workspace:^",
+    "google-auth-library": "^10.5.0",
     "hono": "^4.6.0",
     "puppeteer-core": "^24.39.1",
     "tar": "^7.4.3"

packages/gcp-cloud-run/src/sdk/getRenderProgress.test.ts

@@ -8,6 +8,8 @@ import {
   type ExecutionRecord,
   type ExecutionsGetClientLike,
   getRenderProgress,
+  type StepEntriesListerLike,
+  type StepEntryRecord,
 } from "./getRenderProgress.js";
 
 function fakeExecutions(record: ExecutionRecord): ExecutionsGetClientLike {
@@ -18,6 +20,18 @@ function fakeExecutions(record: ExecutionRecord): ExecutionsGetClientLike {
   };
 }
 
+function fakeStepEntries(entries: StepEntryRecord[]): StepEntriesListerLike {
+  return {
+    async listStepEntries(_executionName: string) {
+      return entries;
+    },
+  };
+}
+
+function succeeded(step: string, count = 1): StepEntryRecord[] {
+  return Array.from({ length: count }, () => ({ step, state: "STATE_SUCCEEDED" }));
+}
+
 const accumulated = JSON.stringify({
   Plan: { TotalFrames: 90, DurationMs: 4000 },
   Chunks: [
@@ -29,17 +43,97 @@ const accumulated = JSON.stringify({
 });
 
 describe("getRenderProgress", () => {
-  it("reports running with no frame data while ACTIVE", async () => {
+  it("reports running with no frame data while ACTIVE and no step entries yet", async () => {
     const p = await getRenderProgress({
       executionName: "x",
       executions: fakeExecutions({ state: "ACTIVE", startTime: { seconds: 1700000000 } }),
+      stepEntries: fakeStepEntries([]),
     });
     expect(p.status).toBe("running");
     expect(p.overallProgress).toBe(0);
     expect(p.totalFrames).toBeNull();
+    expect(p.chunksCompleted).toBe(0);
+    expect(p.totalChunks).toBeNull();
     expect(p.fatalErrorEncountered).toBe(false);
   });
 
+  it("reports chunk-based mid-flight progress from step entries", async () => {
+    const p = await getRenderProgress({
+      executionName: "x",
+      executions: fakeExecutions({ state: "ACTIVE", startTime: { seconds: 1700000000 } }),
+      stepEntries: fakeStepEntries([
+        ...succeeded("plan"),
+        ...succeeded("appendSlots", 4),
+        ...succeeded("renderOneChunk", 2),
+        { step: "renderOneChunk", state: "STATE_IN_PROGRESS" },
+      ]),
+    });
+    expect(p.status).toBe("running");
+    // 10% plan + 80% * (2/4 chunks)
+    expect(p.overallProgress).toBeCloseTo(0.5, 10);
+    expect(p.chunksCompleted).toBe(2);
+    expect(p.totalChunks).toBe(4);
+    expect(p.invocationsObserved).toBe(3); // plan + 2 chunks
+    expect(p.framesRendered).toBe(0); // step entries carry no frame counts
+  });
+
+  it("caps mid-flight progress below 1 once assemble succeeds", async () => {
+    const p = await getRenderProgress({
+      executionName: "x",
+      executions: fakeExecutions({ state: "ACTIVE" }),
+      stepEntries: fakeStepEntries([
+        ...succeeded("plan"),
+        ...succeeded("appendSlots", 2),
+        ...succeeded("renderOneChunk", 2),
+        ...succeeded("assemble"),
+      ]),
+    });
+    expect(p.overallProgress).toBe(0.99);
+    expect(p.chunksCompleted).toBe(2);
+  });
+
+  it("reports plan-only progress once plan succeeds but before the chunk list exists", async () => {
+    const p = await getRenderProgress({
+      executionName: "x",
+      executions: fakeExecutions({ state: "ACTIVE" }),
+      stepEntries: fakeStepEntries(succeeded("plan")),
+    });
+    expect(p.overallProgress).toBeCloseTo(0.1, 10);
+    expect(p.totalChunks).toBeNull();
+  });
+
+  it("degrades to the coarse snapshot when the step-entries read fails", async () => {
+    const p = await getRenderProgress({
+      executionName: "x",
+      executions: fakeExecutions({ state: "ACTIVE" }),
+      stepEntries: {
+        async listStepEntries() {
+          throw new Error("PERMISSION_DENIED");
+        },
+      },
+    });
+    expect(p.status).toBe("running");
+    expect(p.overallProgress).toBe(0);
+    expect(p.chunksCompleted).toBe(0);
+  });
+
+  it("skips the step-entries read when midFlightProgress is false", async () => {
+    let called = false;
+    const p = await getRenderProgress({
+      executionName: "x",
+      executions: fakeExecutions({ state: "ACTIVE" }),
+      midFlightProgress: false,
+      stepEntries: {
+        async listStepEntries() {
+          called = true;
+          return [];
+        },
+      },
+    });
+    expect(called).toBe(false);
+    expect(p.overallProgress).toBe(0);
+  });
+
   it("reports succeeded with parsed frames + cost", async () => {
     const p = await getRenderProgress({
       executionName: "x",
@@ -57,6 +151,8 @@ describe("getRenderProgress", () => {
     expect(p.totalFrames).toBe(90);
     expect(p.framesRendered).toBe(90);
     expect(p.invocationsObserved).toBe(5); // plan + 3 chunks + assemble
+    expect(p.chunksCompleted).toBe(3);
+    expect(p.totalChunks).toBe(3);
     expect(p.outputFile).toEqual({ gcsUri: "gs://b/renders/r1/output.mp4", bytes: 123456 });
     expect(p.costs.accruedSoFarUsd).toBeGreaterThan(0);
     expect(p.costs.breakdown.estimated).toBe(false);