[world-vercel] Send remoteRefBehavior=lazy on v4 metadata-only event listings (#2415)

Author: VaguelySerious

.changeset/v4-lazy-list-refs.md

@@ -0,0 +1,5 @@
+---
+"@workflow/world-vercel": patch
+---
+
+Skip transferring event payload bytes when listing events with `resolveData: 'none'` using the v4 API.

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

@@ -362,6 +362,15 @@ export interface ListEventsV4Params {
   cursor?: string;
   limit?: number;
   sortOrder?: 'asc' | 'desc';
+  /**
+   * Whether the backend resolves payload bytes into each frame body.
+   * `resolve` (default) streams the bytes; `lazy` emits empty-body frames
+   * (the ref descriptor stays in the frame meta) — for metadata-only
+   * listings that would otherwise download every payload just to discard
+   * it. A backend that predates this flag ignores it and streams full
+   * bodies, so callers must still tolerate bodies being present.
+   */
+  remoteRefBehavior?: 'resolve' | 'lazy';
 }
 
 /**
@@ -460,11 +469,23 @@ async function consumeListFrameStream(
   return { events, ...(next ? { next } : {}) };
 }
 
-function paginationToQuery(params: ListEventsV4Params): string {
-  const sp = new URLSearchParams();
+/**
+ * Append the shared list params (pagination + ref behavior) to `sp`.
+ * Shared by the runId and correlationId list query builders so both send
+ * `remoteRefBehavior` identically.
+ */
+function appendListParams(sp: URLSearchParams, params: ListEventsV4Params) {
   if (params.cursor) sp.set('cursor', params.cursor);
   if (params.limit !== undefined) sp.set('limit', String(params.limit));
   if (params.sortOrder) sp.set('sortOrder', params.sortOrder);
+  if (params.remoteRefBehavior) {
+    sp.set('remoteRefBehavior', params.remoteRefBehavior);
+  }
+}
+
+function paginationToQuery(params: ListEventsV4Params): string {
+  const sp = new URLSearchParams();
+  appendListParams(sp, params);
   const qs = sp.toString();
   return qs ? `?${qs}` : '';
 }
@@ -511,9 +532,7 @@ export async function getEventsByCorrelationIdV4(
   const { baseUrl, headers } = await getHttpConfig(config);
   const sp = new URLSearchParams();
   sp.set('correlationId', correlationId);
-  if (params.cursor) sp.set('cursor', params.cursor);
-  if (params.limit !== undefined) sp.set('limit', String(params.limit));
-  if (params.sortOrder) sp.set('sortOrder', params.sortOrder);
+  appendListParams(sp, params);
   const url = `${baseUrl}/v4/events?${sp.toString()}`;
   return consumeListFrameStream(
     url,

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

@@ -2,7 +2,12 @@ import type { AnyEventRequest } from '@workflow/world';
 import { encode } from 'cbor-x';
 import { MockAgent } from 'undici';
 import { describe, expect, it } from 'vitest';
-import { createWorkflowRunEvent, splitEventDataForV4 } from './events.js';
+import {
+  createWorkflowRunEvent,
+  getWorkflowRunEvents,
+  splitEventDataForV4,
+} from './events.js';
+import { encodeFrame, V4_FRAME_CONTENT_TYPE } from './frames.js';
 
 const ORIGIN = 'https://vercel-workflow.com';
 
@@ -344,3 +349,82 @@ describe('createWorkflowRunEvent resolveData', () => {
     agent.assertNoPendingInterceptors();
   });
 });
+
+describe('getWorkflowRunEvents remoteRefBehavior mapping', () => {
+  // A v4 LIST response: one run_created frame (with payload body) + sentinel.
+  function listResponse(body: Uint8Array): Buffer {
+    return Buffer.concat([
+      encodeFrame(
+        {
+          eventId: 'evnt_1',
+          runId: 'wrun_1',
+          eventType: 'run_created',
+          createdAt: '2026-06-10T00:00:00.000Z',
+          eventData: {
+            input: { _type: 'RemoteRef', _ref: 's3rf:wrun_1/input' },
+            workflowName: 'wf',
+          },
+        },
+        body
+      ),
+      encodeFrame({ _end: 1 }, new Uint8Array(0)),
+    ]);
+  }
+
+  it("sends remoteRefBehavior=lazy for resolveData 'none' and strips any returned body", async () => {
+    const agent = mockAgent();
+    // The interceptor only matches when the request carries
+    // ?remoteRefBehavior=lazy — so a missing/wrong param fails the request.
+    // The reply still includes payload bytes, simulating a backend that
+    // predates the flag: the adapter must strip them regardless.
+    agent
+      .get(ORIGIN)
+      .intercept({
+        path: '/api/v4/runs/wrun_1/events',
+        method: 'GET',
+        query: { remoteRefBehavior: 'lazy' },
+      })
+      .reply(200, listResponse(new TextEncoder().encode('"payload"')), {
+        headers: { 'content-type': V4_FRAME_CONTENT_TYPE },
+      });
+
+    const result = await getWorkflowRunEvents(
+      { runId: 'wrun_1', resolveData: 'none' },
+      { token: 'test-token', dispatcher: agent }
+    );
+
+    const eventData = (
+      result.data[0] as { eventData?: Record<string, unknown> }
+    ).eventData;
+    expect(eventData?.input).toBeUndefined();
+    expect(eventData?.workflowName).toBe('wf');
+    agent.assertNoPendingInterceptors();
+  });
+
+  it('sends remoteRefBehavior=resolve by default and splices the body bytes', async () => {
+    const agent = mockAgent();
+    const body = new TextEncoder().encode('"payload"');
+    agent
+      .get(ORIGIN)
+      .intercept({
+        path: '/api/v4/runs/wrun_1/events',
+        method: 'GET',
+        query: { remoteRefBehavior: 'resolve' },
+      })
+      .reply(200, listResponse(body), {
+        headers: { 'content-type': V4_FRAME_CONTENT_TYPE },
+      });
+
+    // No resolveData → defaults to 'all' → resolve.
+    const result = await getWorkflowRunEvents(
+      { runId: 'wrun_1' },
+      { token: 'test-token', dispatcher: agent }
+    );
+
+    const eventData = (
+      result.data[0] as { eventData?: Record<string, unknown> }
+    ).eventData;
+    expect(eventData?.input).toEqual(body);
+    agent.assertNoPendingInterceptors();
+  });
+});

packages/world-vercel/src/events.ts

@@ -460,10 +460,20 @@ export async function getWorkflowRunEvents(
   config?: APIConfig
 ): Promise<PaginatedResponse<Event>> {
   const { pagination, resolveData = DEFAULT_RESOLVE_DATA_OPTION } = params;
+  // `resolveData: 'none'` means the caller only wants metadata — it discards
+  // payloads in buildEventFromV4 below. Tell the backend not to stream them
+  // in the first place (lazy → empty frame bodies). On `'all'` we resolve
+  // (the default). A backend that predates this flag ignores it and streams
+  // full bodies regardless; buildEventFromV4 still strips them when
+  // resolveData is 'none', so this is purely a bandwidth optimization and is
+  // safe against an older backend.
   const wirePagination = {
     cursor: pagination?.cursor ?? undefined,
     limit: pagination?.limit,
     sortOrder: pagination?.sortOrder,
+    remoteRefBehavior: (resolveData === 'none' ? 'lazy' : 'resolve') as
+      | 'lazy'
+      | 'resolve',
   };
 
   const result = await ('correlationId' in params