@lumenflow/surfaces 5.1.0

package/http/control-plane-event-subscriber.ts

@@ -0,0 +1,233 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Disposable, KernelEvent, ReplayFilter } from '@lumenflow/kernel';
+import type { EventSubscriber } from './event-stream.js';
+
+const CONTROL_PLANE_POLICY_DECISION = {
+  DENY: 'deny',
+} as const;
+
+const DIAGNOSTIC_REASON = {
+  POLICY_PULL_FAILED: 'policy pull failed',
+  HEARTBEAT_FAILED: 'heartbeat failed',
+  EVENT_PUSH_FAILED: 'event forwarding failed',
+} as const;
+
+const ACTIONABLE_SYNC_DIAGNOSTIC_SUFFIX = 'Check control_plane.endpoint and auth token.';
+const WORKSPACE_WARNING_EVENT_KIND = 'workspace_warning';
+const KERNEL_EVENT_SCHEMA_VERSION = 1;
+const DEFAULT_SYNC_INTERVAL_MS = 30_000;
+const SYNC_SESSION_ID_PREFIX = 'http-surface-sync';
+const CLOCK_ISO_OFFSET = 36;
+
+interface ControlPlanePolicyRuleLike {
+  id: string;
+  decision: 'allow' | 'deny';
+  reason?: string;
+}
+
+interface ControlPlanePolicySetLike {
+  default_decision: 'allow' | 'deny';
+  rules: ControlPlanePolicyRuleLike[];
+}
+
+export interface ControlPlaneSyncPortLike {
+  pullPolicies(input: { workspace_id: string }): Promise<ControlPlanePolicySetLike>;
+  heartbeat(input: {
+    workspace_id: string;
+    session_id: string;
+  }): Promise<{ status: 'ok'; server_time: string }>;
+  pushKernelEvents(input: {
+    workspace_id: string;
+    events: KernelEvent[];
+  }): Promise<{ accepted: number }>;
+}
+
+export interface ControlPlaneEventSubscriberOptions {
+  controlPlaneSyncPort: ControlPlaneSyncPortLike;
+  workspaceId: string;
+  pollIntervalMs: number;
+  logger?: Pick<Console, 'warn'>;
+  now?: () => Date;
+}
+
+export const DEFAULT_CONTROL_PLANE_SYNC_INTERVAL_MS = DEFAULT_SYNC_INTERVAL_MS;
+
+interface SyncState {
+  allowForwarding: boolean;
+  inFlight: boolean;
+}
+
+function createWorkspaceWarningEvent(message: string, now: () => Date): KernelEvent {
+  return {
+    schema_version: KERNEL_EVENT_SCHEMA_VERSION,
+    kind: WORKSPACE_WARNING_EVENT_KIND,
+    timestamp: now().toISOString(),
+    message,
+  } as KernelEvent;
+}
+
+function createSyncSessionId(now: () => Date): string {
+  return `${SYNC_SESSION_ID_PREFIX}:${now().toISOString().slice(0, CLOCK_ISO_OFFSET)}`;
+}
+
+async function emitDiagnostic(
+  callback: (event: KernelEvent) => void | Promise<void>,
+  logger: Pick<Console, 'warn'> | undefined,
+  workspaceId: string,
+  reason: string,
+  now: () => Date,
+): Promise<void> {
+  const message =
+    `Control plane sync ${reason} for workspace "${workspaceId}". ` +
+    ACTIONABLE_SYNC_DIAGNOSTIC_SUFFIX;
+  logger?.warn?.(message);
+  await callback(createWorkspaceWarningEvent(message, now));
+}
+
+async function runSyncCycle(
+  options: ControlPlaneEventSubscriberOptions,
+  callback: (event: KernelEvent) => void | Promise<void>,
+  sessionId: string,
+  pendingEvents: KernelEvent[],
+  state: SyncState,
+): Promise<void> {
+  if (state.inFlight) {
+    return;
+  }
+  state.inFlight = true;
+  const now = options.now ?? (() => new Date());
+
+  try {
+    try {
+      const pulledPolicies = await options.controlPlaneSyncPort.pullPolicies({
+        workspace_id: options.workspaceId,
+      });
+      state.allowForwarding =
+        pulledPolicies.default_decision !== CONTROL_PLANE_POLICY_DECISION.DENY;
+    } catch {
+      state.allowForwarding = false;
+      await emitDiagnostic(
+        callback,
+        options.logger,
+        options.workspaceId,
+        DIAGNOSTIC_REASON.POLICY_PULL_FAILED,
+        now,
+      );
+      return;
+    }
+
+    try {
+      await options.controlPlaneSyncPort.heartbeat({
+        workspace_id: options.workspaceId,
+        session_id: sessionId,
+      });
+    } catch {
+      await emitDiagnostic(
+        callback,
+        options.logger,
+        options.workspaceId,
+        DIAGNOSTIC_REASON.HEARTBEAT_FAILED,
+        now,
+      );
+      return;
+    }
+
+    if (!state.allowForwarding || pendingEvents.length === 0) {
+      return;
+    }
+
+    const batch = pendingEvents.splice(0, pendingEvents.length);
+    try {
+      await options.controlPlaneSyncPort.pushKernelEvents({
+        workspace_id: options.workspaceId,
+        events: batch,
+      });
+    } catch {
+      pendingEvents.unshift(...batch);
+      state.allowForwarding = false;
+      await emitDiagnostic(
+        callback,
+        options.logger,
+        options.workspaceId,
+        DIAGNOSTIC_REASON.EVENT_PUSH_FAILED,
+        now,
+      );
+    }
+  } finally {
+    state.inFlight = false;
+  }
+}
+
+export function wrapEventSubscriberWithControlPlaneSync(
+  source: EventSubscriber,
+  options: ControlPlaneEventSubscriberOptions,
+): EventSubscriber {
+  const resolvedIntervalMs =
+    options.pollIntervalMs > 0 ? options.pollIntervalMs : DEFAULT_CONTROL_PLANE_SYNC_INTERVAL_MS;
+
+  return {
+    subscribe(
+      filter: ReplayFilter,
+      callback: (event: KernelEvent) => void | Promise<void>,
+    ): Disposable {
+      const pendingEvents: KernelEvent[] = [];
+      const state: SyncState = {
+        allowForwarding: true,
+        inFlight: false,
+      };
+      const now = options.now ?? (() => new Date());
+      const sessionId = createSyncSessionId(now);
+
+      const wrappedCallback = async (event: KernelEvent): Promise<void> => {
+        await callback(event);
+        pendingEvents.push(event);
+      };
+
+      const sourceSubscription = source.subscribe(filter, wrappedCallback);
+      const timer = setInterval(() => {
+        void runSyncCycle(options, callback, sessionId, pendingEvents, state);
+      }, resolvedIntervalMs);
+
+      return {
+        dispose: () => {
+          clearInterval(timer);
+          sourceSubscription.dispose();
+        },
+      };
+    },
+  };
+}
+
+/**
+ * Creates an EventSubscriber that can be used by the dashboard to
+ * optionally read events from the control plane instead of a local
+ * EventStore. This enables centralized observability for organizations
+ * where the web dashboard may not have direct access to the local
+ * event-store file.
+ *
+ * Note: This is a push-side bridge. The subscriber interface allows
+ * the dashboard to subscribe to events that are forwarded through the
+ * control plane, enabling the same SSE streaming pattern as local mode.
+ */
+export function createControlPlaneEventSubscriber(
+  _options: ControlPlaneEventSubscriberOptions,
+): EventSubscriber {
+  return {
+    subscribe(
+      _filter: ReplayFilter,
+      _callback: (event: KernelEvent) => void | Promise<void>,
+    ): Disposable {
+      // The control plane event subscriber provides the interface contract
+      // for dashboard integration. The actual polling/streaming implementation
+      // will be wired when the control plane SDK exposes a pull/subscribe
+      // endpoint for kernel events.
+      return {
+        dispose: () => {
+          // Cleanup when subscription is no longer needed.
+        },
+      };
+    },
+  };
+}

package/http/event-stream.ts

@@ -0,0 +1,216 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+  KERNEL_EVENT_KINDS,
+  type Disposable,
+  type KernelEvent,
+  type ReplayFilter,
+  type ToolTraceEntry,
+} from '@lumenflow/kernel';
+
+const HTTP_METHOD = {
+  GET: 'GET',
+} as const;
+
+const HTTP_STATUS = {
+  OK: 200,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  NOT_IMPLEMENTED: 501,
+} as const;
+
+const HEADER = {
+  CACHE_CONTROL: 'cache-control',
+  CONNECTION: 'connection',
+  CONTENT_TYPE: 'content-type',
+} as const;
+
+const HEADER_VALUE = {
+  CACHE_CONTROL: 'no-cache',
+  CONNECTION: 'keep-alive',
+  EVENT_STREAM: 'text/event-stream; charset=utf-8',
+} as const;
+
+const JSON_RESPONSE_KEY_ERROR = 'error';
+const JSON_RESPONSE_KEY_MESSAGE = 'message';
+const SSE_DATA_PREFIX = 'data: ';
+const SSE_DOUBLE_NEWLINE = '\n\n';
+const SSE_HEARTBEAT_COMMENT = ':heartbeat\n\n';
+const HEARTBEAT_INTERVAL_MS = 15_000;
+const SEARCH_PARAM = {
+  KIND: 'kind',
+  SINCE_TIMESTAMP: 'sinceTimestamp',
+  UNTIL_TIMESTAMP: 'untilTimestamp',
+} as const;
+
+const REPLAY_KIND_VALUES = new Set<KernelEvent['kind']>(
+  Object.values(KERNEL_EVENT_KINDS) as KernelEvent['kind'][],
+);
+
+/**
+ * StreamEvent envelope: discriminated union wrapping either a KernelEvent
+ * (source: 'kernel') or a ToolTraceEntry (source: 'evidence').
+ *
+ * Option B from WU-1918 spec notes.
+ */
+export type StreamEvent =
+  | { source: 'kernel'; event: KernelEvent }
+  | { source: 'evidence'; trace: ToolTraceEntry };
+
+export interface EventSubscriber {
+  subscribe(
+    filter: ReplayFilter,
+    callback: (event: KernelEvent) => void | Promise<void>,
+  ): Disposable;
+}
+
+export interface TraceSubscriber {
+  subscribe(taskId: string, callback: (trace: ToolTraceEntry) => void): Disposable;
+}
+
+export interface EventStreamRouterOptions {
+  traceSubscriber?: TraceSubscriber;
+}
+
+export interface EventStreamRouter {
+  handleRequest(
+    request: IncomingMessage,
+    response: ServerResponse<IncomingMessage>,
+    routeSegments: string[],
+    searchParams: URLSearchParams,
+  ): Promise<boolean>;
+}
+
+function writeJsonError(
+  response: ServerResponse<IncomingMessage>,
+  statusCode: number,
+  message: string,
+): void {
+  response.statusCode = statusCode;
+  response.setHeader(HEADER.CONTENT_TYPE, 'application/json; charset=utf-8');
+  response.end(
+    JSON.stringify({
+      [JSON_RESPONSE_KEY_ERROR]: {
+        [JSON_RESPONSE_KEY_MESSAGE]: message,
+      },
+    }),
+  );
+}
+
+function toKindFilter(searchParams: URLSearchParams): ReplayFilter['kind'] {
+  const values = searchParams
+    .getAll(SEARCH_PARAM.KIND)
+    .map((value) => value.trim())
+    .filter((value): value is KernelEvent['kind'] => {
+      return value.length > 0 && REPLAY_KIND_VALUES.has(value as KernelEvent['kind']);
+    });
+
+  if (values.length === 0) {
+    return undefined;
+  }
+  if (values.length === 1) {
+    return values[0];
+  }
+  return values;
+}
+
+function toReplayFilter(taskId: string, searchParams: URLSearchParams): ReplayFilter {
+  const sinceTimestamp = searchParams.get(SEARCH_PARAM.SINCE_TIMESTAMP) ?? undefined;
+  const untilTimestamp = searchParams.get(SEARCH_PARAM.UNTIL_TIMESTAMP) ?? undefined;
+  return {
+    taskId,
+    kind: toKindFilter(searchParams),
+    sinceTimestamp,
+    untilTimestamp,
+  };
+}
+
+function writeEventStreamHeaders(response: ServerResponse<IncomingMessage>): void {
+  response.statusCode = HTTP_STATUS.OK;
+  response.setHeader(HEADER.CONTENT_TYPE, HEADER_VALUE.EVENT_STREAM);
+  response.setHeader(HEADER.CACHE_CONTROL, HEADER_VALUE.CACHE_CONTROL);
+  response.setHeader(HEADER.CONNECTION, HEADER_VALUE.CONNECTION);
+}
+
+function writeStreamEvent(response: ServerResponse<IncomingMessage>, envelope: StreamEvent): void {
+  const payload = `${SSE_DATA_PREFIX}${JSON.stringify(envelope)}${SSE_DOUBLE_NEWLINE}`;
+  response.write(payload);
+}
+
+export function createEventStreamRouter(
+  eventSubscriber?: EventSubscriber,
+  options?: EventStreamRouterOptions,
+): EventStreamRouter {
+  return {
+    async handleRequest(
+      request: IncomingMessage,
+      response: ServerResponse<IncomingMessage>,
+      routeSegments: string[],
+      searchParams: URLSearchParams,
+    ): Promise<boolean> {
+      if (routeSegments.length !== 1) {
+        writeJsonError(response, HTTP_STATUS.NOT_FOUND, 'Route not found.');
+        return true;
+      }
+
+      if ((request.method ?? '') !== HTTP_METHOD.GET) {
+        writeJsonError(response, HTTP_STATUS.METHOD_NOT_ALLOWED, 'Unsupported method.');
+        return true;
+      }
+
+      if (!eventSubscriber) {
+        writeJsonError(response, HTTP_STATUS.NOT_IMPLEMENTED, 'Event streaming is unavailable.');
+        return true;
+      }
+
+      const taskId = routeSegments[0] ?? '';
+      const filter = toReplayFilter(taskId, searchParams);
+
+      writeEventStreamHeaders(response);
+
+      let isDisposed = false;
+
+      const eventSub = eventSubscriber.subscribe(filter, async (event) => {
+        if (isDisposed) {
+          return;
+        }
+        writeStreamEvent(response, { source: 'kernel', event });
+      });
+
+      let traceSub: Disposable | undefined;
+      if (options?.traceSubscriber) {
+        traceSub = options.traceSubscriber.subscribe(taskId, (trace) => {
+          if (isDisposed) {
+            return;
+          }
+          writeStreamEvent(response, { source: 'evidence', trace });
+        });
+      }
+
+      const heartbeatTimer = setInterval(() => {
+        if (isDisposed) {
+          return;
+        }
+        response.write(SSE_HEARTBEAT_COMMENT);
+      }, HEARTBEAT_INTERVAL_MS);
+
+      const dispose = (): void => {
+        if (isDisposed) {
+          return;
+        }
+        isDisposed = true;
+        clearInterval(heartbeatTimer);
+        eventSub.dispose();
+        traceSub?.dispose();
+      };
+
+      request.on('close', dispose);
+      response.on('close', dispose);
+      response.on('finish', dispose);
+
+      return true;
+    },
+  };
+}

package/http/index.ts

@@ -0,0 +1,10 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+export * from './server.js';
+export * from './ag-ui-adapter.js';
+export * from './run-agent.js';
+export * from './tool-api.js';
+export * from './tool-discovery.js';
+export * from './control-plane-event-subscriber.js';
+export * from './sidecar-entry.js';