[core] Surface workflowCoreVersion from healthCheck() result

.changeset/healthcheck-coreversion.md

@@ -0,0 +1,6 @@
+---
+"@workflow/core": minor
+"workflow": minor
+---
+
+Surface `workflowCoreVersion` from the responding deployment in `healthCheck()` results.

packages/core/e2e/e2e.test.ts

@@ -1957,6 +1957,10 @@ describe('e2e', () => {
         timeout: 30000,
       });
       expect(workflowResult.healthy).toBe(true);
+      // The deployed app advertises its `@workflow/core` version so
+      // callers can derive capability metadata (see `getRunCapabilities`
+      // in `capabilities.ts`).
+      expect(typeof workflowResult.workflowCoreVersion).toBe('string');
     }
   );
 

packages/core/src/runtime/helpers.test.ts

@@ -1,7 +1,11 @@
 import { WorkflowWorldError } from '@workflow/errors';
-import type { Event } from '@workflow/world';
+import type { Event, World } from '@workflow/world';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { getWorkflowQueueName, loadWorkflowRunEvents } from './helpers.js';
+import {
+  getWorkflowQueueName,
+  healthCheck,
+  loadWorkflowRunEvents,
+} from './helpers.js';
 
 // Mock the logger to suppress output during tests
 vi.mock('../logger.js', () => ({
@@ -102,6 +106,108 @@ describe('getWorkflowQueueName', () => {
   });
 });
 
+describe('healthCheck response parsing', () => {
+  /**
+   * Builds a minimal `World` whose `streams.get(...)` returns a stream of
+   * the supplied response text, simulating what the responding deployment
+   * would write via `handleHealthCheckMessage`. Just enough surface for
+   * `healthCheck()` to exercise its parse path.
+   */
+  function makeWorldWithResponse(responseText: string): World {
+    return {
+      queue: vi.fn().mockResolvedValue(undefined),
+      streams: {
+        get: vi.fn(async () => {
+          let delivered = false;
+          return new ReadableStream<Uint8Array>({
+            pull(controller) {
+              if (!delivered) {
+                controller.enqueue(new TextEncoder().encode(responseText));
+                delivered = true;
+              } else {
+                controller.close();
+              }
+            },
+          });
+        }),
+      },
+    } as unknown as World;
+  }
+
+  it('surfaces workflowCoreVersion when present in the response', async () => {
+    const world = makeWorldWithResponse(
+      JSON.stringify({
+        healthy: true,
+        endpoint: 'workflow',
+        specVersion: 3,
+        workflowCoreVersion: '5.0.0-beta.7',
+        timestamp: Date.now(),
+      })
+    );
+
+    const result = await healthCheck(world, 'workflow', { timeout: 1000 });
+
+    expect(result.healthy).toBe(true);
+    expect(result.specVersion).toBe(3);
+    expect(result.workflowCoreVersion).toBe('5.0.0-beta.7');
+  });
+
+  it('omits workflowCoreVersion when the response does not include the field', async () => {
+    // Independent of specVersion — the field is omitted by any responder
+    // running an older `@workflow/core` that predates the addition of
+    // `workflowCoreVersion` to the health response payload.
+    const world = makeWorldWithResponse(
+      JSON.stringify({
+        healthy: true,
+        endpoint: 'workflow',
+        specVersion: 3,
+        // No workflowCoreVersion field
+        timestamp: Date.now(),
+      })
+    );
+
+    const result = await healthCheck(world, 'workflow', { timeout: 1000 });
+
+    expect(result.healthy).toBe(true);
+    expect(result.specVersion).toBe(3);
+    expect(result.workflowCoreVersion).toBeUndefined();
+  });
+
+  it('omits workflowCoreVersion when the field is the wrong type', async () => {
+    // Defensive: the parser only accepts strings. Anything else is dropped
+    // rather than surfaced as garbage.
+    const world = makeWorldWithResponse(
+      JSON.stringify({
+        healthy: true,
+        endpoint: 'workflow',
+        specVersion: 3,
+        workflowCoreVersion: 12345,
+        timestamp: Date.now(),
+      })
+    );
+
+    const result = await healthCheck(world, 'workflow', { timeout: 1000 });
+
+    expect(result.healthy).toBe(true);
+    expect(result.workflowCoreVersion).toBeUndefined();
+  });
+
+  it('returns healthy with no fields for non-JSON plain-text responses', async () => {
+    // Some deployments respond with plain text like
+    // 'Workflow SDK "..." endpoint is healthy'. The parser treats any
+    // non-empty non-JSON text as healthy, with no version metadata.
+    const world = makeWorldWithResponse(
+      'Workflow SDK "workflow" endpoint is healthy'
+    );
+
+    const result = await healthCheck(world, 'workflow', { timeout: 1000 });
+
+    expect(result.healthy).toBe(true);
+    expect(result.specVersion).toBeUndefined();
+    expect(result.workflowCoreVersion).toBeUndefined();
+  });
+});
+
 describe('loadWorkflowRunEvents', () => {
   beforeEach(() => {
     eventsListMock.mockReset();

packages/core/src/runtime/helpers.ts

@@ -64,6 +64,14 @@ export interface HealthCheckResult {
   latencyMs?: number;
   /** Spec version of the responding deployment */
   specVersion?: number;
+  /**
+   * `@workflow/core` version of the responding deployment, used for
+   * capability detection (see `getRunCapabilities`). Omitted when the
+   * responding deployment did not provide the field as a string —
+   * for example, an older `@workflow/core` that predates this field,
+   * or a non-JSON plain-text health response.
+   */
+  workflowCoreVersion?: string;
 }
 
 /**
@@ -180,9 +188,11 @@ async function readStreamWithTimeout(
  * Parse and validate a health check response from stream chunks.
  * Returns the parsed response or null if invalid.
  */
-function parseHealthCheckResponse(
-  chunks: Uint8Array[]
-): { healthy: boolean } | null {
+function parseHealthCheckResponse(chunks: Uint8Array[]): {
+  healthy: boolean;
+  specVersion?: number;
+  workflowCoreVersion?: string;
+} | null {
   if (chunks.length === 0) return null;
 
   const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
@@ -217,12 +227,19 @@ function parseHealthCheckResponse(
   }
 
   const r = response as Record<string, unknown>;
-  const parsed: { healthy: boolean; specVersion?: number } = {
+  const parsed: {
+    healthy: boolean;
+    specVersion?: number;
+    workflowCoreVersion?: string;
+  } = {
     healthy: r.healthy as boolean,
   };
   if (typeof r.specVersion === 'number') {
     parsed.specVersion = r.specVersion;
   }
+  if (typeof r.workflowCoreVersion === 'string') {
+    parsed.workflowCoreVersion = r.workflowCoreVersion;
+  }
   return parsed;
 }