feat(world-vercel): export openEventsChannel for writers outside a queue delivery (#4469)

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: pranaygp

.changeset/world-vercel-export-events-channel.md

@@ -0,0 +1,5 @@
+---
+'@workflow/world-vercel': patch
+---
+
+Export `openEventsChannel` so code writing a run's events outside a queue delivery can use the WebSocket events transport.

packages/world-vercel/README.md

@@ -12,6 +12,30 @@ Backend connection failures and interrupted event streams follow existing retry
 
 See [Backend connection failures](https://workflow-sdk.dev/docs/foundations/errors-and-retries#backend-connection-failures) for retry behavior and diagnostics.
 
+## Events channel
+
+Event writes go over a per-run WebSocket (the default `WORKFLOW_EVENTS_TRANSPORT`)
+only while that run's channel is open. The queue handler opens it for each
+delivery, so workflows need nothing extra. Code that writes a run's events
+outside a delivery (a custom driver, a long-lived process) opens and releases
+it itself; otherwise those writes go over HTTP:
+
+```ts
+import { createWorld, openEventsChannel } from '@workflow/world-vercel';
+
+const world = createWorld();
+const release = openEventsChannel(runId);
+try {
+  await world.events.create(runId, event);
+} finally {
+  release?.();
+}
+```
+
+It returns `undefined`, and writes stay on HTTP, when the transport is
+disabled or the World cannot hold a socket (a `projectConfig` World, as the
+CLI uses).
+
 ## Custom dispatcher
 
 HTTP requests (including the queue) default to a shared undici `RetryAgent` that handles connection pooling and retries. Pass a custom `dispatcher` to override it, for example, to tune undici on newer Node.js runtimes:

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

@@ -0,0 +1,30 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { openEventsChannel } from './index.js';
+
+describe('openEventsChannel', () => {
+  const previous = process.env.WORKFLOW_EVENTS_TRANSPORT;
+  afterEach(() => {
+    if (previous === undefined) delete process.env.WORKFLOW_EVENTS_TRANSPORT;
+    else process.env.WORKFLOW_EVENTS_TRANSPORT = previous;
+  });
+
+  it('is exported from the package root', () => {
+    expect(typeof openEventsChannel).toBe('function');
+  });
+
+  it('returns undefined, so writes stay on HTTP, when the transport is disabled', () => {
+    process.env.WORKFLOW_EVENTS_TRANSPORT = 'http';
+    expect(
+      openEventsChannel('wrun_01ARZ3NDEKTSV4RRFFQ69G5FAV')
+    ).toBeUndefined();
+  });
+
+  it('returns undefined for a projectConfig World, which cannot hold a socket', () => {
+    delete process.env.WORKFLOW_EVENTS_TRANSPORT;
+    expect(
+      openEventsChannel('wrun_01ARZ3NDEKTSV4RRFFQ69G5FAV', {
+        projectConfig: { projectId: 'prj_test', teamId: 'team_test' },
+      } as never)
+    ).toBeUndefined();
+  });
+});

packages/world-vercel/src/index.ts

@@ -22,6 +22,15 @@ export { createQueue } from './queue.js';
 export { createStorage } from './storage.js';
 export { createStreamer } from './streamer.js';
 export type { APIConfig } from './utils.js';
+/**
+ * Open a run's WebSocket events channel and return its release (or
+ * `undefined` when the World writes over HTTP). Event writes for that run go
+ * over the socket while at least one claim is held. The flow route already
+ * does this for queue deliveries; call it yourself when you write a run's
+ * events from anywhere else, and call the release when you are done, or the
+ * open socket keeps the process alive.
+ */
+export { openWsChannel as openEventsChannel } from './ws-transport.js';
 
 export function createWorld(config?: APIConfig): World {
   // Project ID for HKDF key derivation context.