[world-vercel] Honor hasMore flag from v4 list pagination endpoint (#2486)

Author: VaguelySerious

.changeset/v4-list-explicit-hasmore.md

@@ -0,0 +1,5 @@
+---
+'@workflow/world-vercel': patch
+---
+
+Honor the server's explicit pagination flag when listing run events, avoiding one extra empty-page request per event-log load on replay.

packages/world-vercel/src/events-v4.test.ts

@@ -132,6 +132,74 @@ describe('getWorkflowRunEventsV4 over HTTP', () => {
     agent.assertNoPendingInterceptors();
   });
 
+  it('captures an explicit hasMore from the sentinel, independent of next', async () => {
+    const origin = 'https://vercel-workflow.com';
+    const agent = new MockAgent();
+    agent.disableNetConnect();
+
+    // The regression shape: a final page still carries a trailing `next`
+    // cursor (incremental-load resume point) but hasMore is false.
+    const frames = Buffer.concat([
+      encodeFrame(
+        {
+          eventId: 'evnt_1',
+          runId: 'wrun_1',
+          eventType: 'run_created',
+          createdAt: '2026-06-10T00:00:00.000Z',
+          eventData: {},
+        },
+        new Uint8Array(0)
+      ),
+      encodeFrame(
+        { _end: 1, next: 'eid:last', hasMore: false },
+        new Uint8Array(0)
+      ),
+    ]);
+
+    agent
+      .get(origin)
+      .intercept({ path: '/api/v4/runs/wrun_1/events', method: 'GET' })
+      .reply(200, frames, {
+        headers: { 'content-type': V4_FRAME_CONTENT_TYPE },
+      });
+
+    const result = await getWorkflowRunEventsV4(
+      'wrun_1',
+      {},
+      { token: 'test-token', dispatcher: agent }
+    );
+
+    expect(result.next).toBe('eid:last');
+    expect(result.hasMore).toBe(false);
+  });
+
+  it('leaves hasMore undefined for a legacy sentinel without the flag', async () => {
+    const origin = 'https://vercel-workflow.com';
+    const agent = new MockAgent();
+    agent.disableNetConnect();
+
+    const frames = encodeFrame(
+      { _end: 1, next: 'cursor-2' },
+      new Uint8Array(0)
+    );
+
+    agent
+      .get(origin)
+      .intercept({ path: '/api/v4/runs/wrun_1/events', method: 'GET' })
+      .reply(200, frames, {
+        headers: { 'content-type': V4_FRAME_CONTENT_TYPE },
+      });
+
+    const result = await getWorkflowRunEventsV4(
+      'wrun_1',
+      {},
+      { token: 'test-token', dispatcher: agent }
+    );
+
+    expect(result.next).toBe('cursor-2');
+    expect(result.hasMore).toBeUndefined();
+  });
+
   it('throws when the stream ends without the end sentinel (truncated response)', async () => {
     const origin = 'https://vercel-workflow.com';
     const agent = new MockAgent();

packages/world-vercel/src/events-v4.ts

@@ -11,7 +11,7 @@
  *   the server stores without ever decoding it.
  * - **GET single event**: response body is one frame.
  * - **LIST events**: response body is a stream of frames terminated by a
- *   sentinel frame (meta = `{_end: 1, next?: cursor}`).
+ *   sentinel frame (meta = `{_end: 1, next?: cursor, hasMore?: boolean}`).
  *
  * Requests carry special HTTP response headers (eventId / runId / createdAt)
  * for client convenience, to allow metadata access without decoding the body.
@@ -388,8 +388,18 @@ export interface ListedEventV4 {
 
 export interface ListEventsV4Result {
   events: ListedEventV4[];
-  /** Pagination cursor — present when more pages remain. */
+  /**
+   * Trailing cursor. Present even on the final page — it doubles as the
+   * resume point for incremental loads — so it is NOT a reliable "more
+   * pages" signal on its own. Use `hasMore` for that.
+   */
   next?: string;
+  /**
+   * Explicit "another page of results exists" flag from the sentinel.
+   * `undefined` against older servers that don't emit it, in which case
+   * the caller falls back to `Boolean(next)`.
+   */
+  hasMore?: boolean;
 }
 
 /**
@@ -440,10 +450,12 @@ async function consumeListFrameStream(
 
   const events: ListedEventV4[] = [];
   let next: string | undefined;
+  let hasMore: boolean | undefined;
   let sawEndSentinel = false;
   for await (const frame of decodeFrames(chunks)) {
     if (frame.meta._end === 1) {
       if (typeof frame.meta.next === 'string') next = frame.meta.next;
+      if (typeof frame.meta.hasMore === 'boolean') hasMore = frame.meta.hasMore;
       sawEndSentinel = true;
       break;
     }
@@ -466,7 +478,11 @@ async function consumeListFrameStream(
     );
   }
 
-  return { events, ...(next ? { next } : {}) };
+  return {
+    events,
+    ...(next ? { next } : {}),
+    ...(hasMore !== undefined ? { hasMore } : {}),
+  };
 }
 
 /**

packages/world-vercel/src/events.test.ts

@@ -428,3 +428,83 @@ describe('getWorkflowRunEvents remoteRefBehavior mapping', () => {
     agent.assertNoPendingInterceptors();
   });
 });
+
+/**
+ * The v4 LIST sentinel carries a trailing `next` cursor even on the final
+ * page (it doubles as the incremental-load resume point), so the runtime's
+ * `while (hasMore)` replay loader must key off the server's explicit
+ * `hasMore` — not `Boolean(next)` — to avoid one wasted empty-page request
+ * per event-log load. Older servers omit the flag; the Boolean(next)
+ * fallback preserves their (correct, if slower) behavior.
+ */
+describe('getWorkflowRunEvents hasMore mapping', () => {
+  function mockListResponse(agent: MockAgent, sentinelMeta: object) {
+    const frames = Buffer.concat([
+      encodeFrame(
+        {
+          eventId: 'evnt_1',
+          runId: 'wrun_1',
+          eventType: 'run_created',
+          createdAt: '2026-06-10T00:00:00.000Z',
+          eventData: {},
+        },
+        new Uint8Array(0)
+      ),
+      encodeFrame(sentinelMeta as Record<string, unknown>, new Uint8Array(0)),
+    ]);
+    agent
+      .get(ORIGIN)
+      .intercept({
+        path: '/api/v4/runs/wrun_1/events',
+        method: 'GET',
+        // These tests use the default resolveData ('all' → resolve), which
+        // the adapter forwards as a query param; match it so the mock fires.
+        query: { remoteRefBehavior: 'resolve' },
+      })
+      .reply(200, frames, {
+        headers: { 'content-type': V4_FRAME_CONTENT_TYPE },
+      });
+  }
+
+  it('honors an explicit hasMore:false even when a trailing cursor is present', async () => {
+    const agent = mockAgent();
+    mockListResponse(agent, { _end: 1, next: 'eid:last', hasMore: false });
+
+    const result = await getWorkflowRunEvents(
+      { runId: 'wrun_1' },
+      { token: 'test-token', dispatcher: agent }
+    );
+
+    expect(result.data).toHaveLength(1);
+    expect(result.hasMore).toBe(false);
+    // The cursor still rides along for incremental loads.
+    expect(result.cursor).toBe('eid:last');
+    agent.assertNoPendingInterceptors();
+  });
+
+  it('maps an explicit hasMore:true through', async () => {
+    const agent = mockAgent();
+    mockListResponse(agent, { _end: 1, next: 'cursor-2', hasMore: true });
+
+    const result = await getWorkflowRunEvents(
+      { runId: 'wrun_1' },
+      { token: 'test-token', dispatcher: agent }
+    );
+
+    expect(result.hasMore).toBe(true);
+    expect(result.cursor).toBe('cursor-2');
+  });
+
+  it('falls back to Boolean(next) against a legacy server without the flag', async () => {
+    const agent = mockAgent();
+    mockListResponse(agent, { _end: 1, next: 'cursor-2' });
+
+    const result = await getWorkflowRunEvents(
+      { runId: 'wrun_1' },
+      { token: 'test-token', dispatcher: agent }
+    );
+
+    expect(result.hasMore).toBe(true);
+    expect(result.cursor).toBe('cursor-2');
+  });
+});

packages/world-vercel/src/events.ts

@@ -22,7 +22,8 @@
  *   - GET single event returns one v4 frame: the event entity in the
  *     frame meta, the user payload bytes in the frame body.
  *   - LIST events returns a stream of v4 frames terminated by a sentinel
- *     frame whose meta carries `{_end: 1, next?: cursor}`. The old
+ *     frame whose meta carries `{_end: 1, next?: cursor, hasMore?: boolean}`.
+ *     The old
  *     per-event `/refs` round-trip is eliminated.
  *
  * Public function signatures are unchanged: storage.ts continues to
@@ -486,8 +487,15 @@ export async function getWorkflowRunEvents(
 
   return {
     data: events,
+    // `next` is present even on the final page (it's the incremental-load
+    // resume cursor), so prefer the server's explicit `hasMore`. The
+    // `Boolean(next)` fallback covers older servers that don't emit it —
+    // at the cost of one extra empty-page request per load.
     cursor: result.next ?? null,
-    hasMore: Boolean(result.next),
+    hasMore:
+      typeof result.hasMore === 'boolean'
+        ? result.hasMore
+        : Boolean(result.next),
   } as PaginatedResponse<Event>;
 }
 

packages/world-vercel/src/frames.ts

@@ -5,7 +5,7 @@
  *
  *   list-response := frame*  end-frame
  *   frame         := u32_be(meta_len) || cbor_meta || u32_be(body_len) || body_bytes
- *   end-frame     := u32_be(meta_len) || cbor_meta {_end: 1, next?: string} || u32_be(0)
+ *   end-frame     := u32_be(meta_len) || cbor_meta {_end: 1, next?: string, hasMore?: boolean} || u32_be(0)
  */
 
 import { decode, encode } from 'cbor-x';