@lumenflow/surfaces 5.1.0

package/http/server.ts

@@ -0,0 +1,329 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { PassThrough } from 'node:stream';
+import type {
+  Disposable,
+  ExecutionContext,
+  KernelEvent,
+  KernelRuntime,
+  ReplayFilter,
+} from '@lumenflow/kernel';
+import { createEventStreamRouter, type EventSubscriber } from './event-stream.js';
+import { createRunAgentRouter } from './run-agent.js';
+import { createTaskApiRouter } from './task-api.js';
+import { createToolApiRouter, type ToolApiRouter } from './tool-api.js';
+import {
+  createToolDiscoveryRouter,
+  type ToolDiscoveryEntryInput,
+  type ToolDiscoveryRouter,
+} from './tool-discovery.js';
+import {
+  DEFAULT_CONTROL_PLANE_SYNC_INTERVAL_MS,
+  type ControlPlaneSyncPortLike,
+  wrapEventSubscriberWithControlPlaneSync,
+} from './control-plane-event-subscriber.js';
+
+const URL_BASE = 'http://localhost';
+const ROUTE_SEGMENT = {
+  TASKS: 'tasks',
+  TOOLS: 'tools',
+  EVENTS: 'events',
+  AG_UI: 'ag-ui',
+} as const;
+const AG_UI_RUN_PATH_SEGMENTS = ['ag-ui', 'v1', 'run'] as const;
+const HTTP_METHOD_POST = 'POST';
+const DEFAULT_SURFACES_VERSION = '0.0.0-unversioned';
+const DEFAULT_WORKSPACE_ID = 'workspace-default';
+const HTTP_STATUS_NOT_FOUND = 404;
+const HEADER_CONTENT_TYPE = 'content-type';
+const CONTENT_TYPE_JSON = 'application/json; charset=utf-8';
+const RESPONSE_ERROR_KEY = 'error';
+const RESPONSE_MESSAGE_KEY = 'message';
+
+export interface QueuedToolDispatchRequest {
+  tool_name: string;
+  input?: unknown;
+  context: ExecutionContext;
+}
+
+export interface QueuedToolDispatchResult {
+  statusCode: number;
+  body: unknown;
+  headers: Record<string, string>;
+}
+
+interface RuntimeEventStoreLike {
+  subscribe(
+    filter: ReplayFilter,
+    callback: (event: KernelEvent) => void | Promise<void>,
+  ): Disposable;
+}
+
+interface RuntimeWithSubscribeEvents extends KernelRuntime {
+  subscribeEvents?: RuntimeEventStoreLike['subscribe'];
+}
+
+interface RuntimeWithPrivateEventStore extends KernelRuntime {
+  eventStore?: RuntimeEventStoreLike;
+}
+
+export interface HttpSurfaceOptions {
+  eventSubscriber?: EventSubscriber;
+  controlPlaneSyncPort?: ControlPlaneSyncPortLike;
+  workspaceId?: string;
+  controlPlaneSyncIntervalMs?: number;
+  controlPlaneDiagnosticsLogger?: Pick<Console, 'warn'>;
+  allowlistedTools?: readonly string[];
+  toolCatalog?: readonly ToolDiscoveryEntryInput[];
+  surfacesVersion?: string;
+}
+
+export interface HttpSurface {
+  handleRequest(request: IncomingMessage, response: ServerResponse<IncomingMessage>): Promise<void>;
+  dispatchQueuedToolCommand?(input: QueuedToolDispatchRequest): Promise<QueuedToolDispatchResult>;
+}
+
+function parseRoute(request: IncomingMessage): {
+  segments: string[];
+  searchParams: URLSearchParams;
+} {
+  const url = new URL(request.url ?? '/', URL_BASE);
+  const segments = url.pathname.split('/').filter((segment) => segment.length > 0);
+  return {
+    segments,
+    searchParams: url.searchParams,
+  };
+}
+
+function writeNotFound(response: ServerResponse<IncomingMessage>): void {
+  response.statusCode = HTTP_STATUS_NOT_FOUND;
+  response.setHeader(HEADER_CONTENT_TYPE, CONTENT_TYPE_JSON);
+  response.end(
+    JSON.stringify({
+      [RESPONSE_ERROR_KEY]: {
+        [RESPONSE_MESSAGE_KEY]: 'Route not found.',
+      },
+    }),
+  );
+}
+
+function matchesRunAgentRoute(segments: string[]): boolean {
+  if (segments.length !== AG_UI_RUN_PATH_SEGMENTS.length) {
+    return false;
+  }
+  return segments.every((segment, index) => segment === AG_UI_RUN_PATH_SEGMENTS[index]);
+}
+
+function resolveEventSubscriber(
+  runtime: KernelRuntime,
+  options: HttpSurfaceOptions,
+): EventSubscriber | undefined {
+  let subscriber: EventSubscriber | undefined;
+
+  if (options.eventSubscriber) {
+    subscriber = options.eventSubscriber;
+  } else {
+    const runtimeWithSubscribeEvents = runtime as RuntimeWithSubscribeEvents;
+    if (typeof runtimeWithSubscribeEvents.subscribeEvents === 'function') {
+      subscriber = {
+        subscribe: runtimeWithSubscribeEvents.subscribeEvents.bind(runtimeWithSubscribeEvents),
+      };
+    } else {
+      const runtimeWithPrivateEventStore = runtime as RuntimeWithPrivateEventStore;
+      if (runtimeWithPrivateEventStore.eventStore) {
+        subscriber = runtimeWithPrivateEventStore.eventStore;
+      }
+    }
+  }
+
+  if (subscriber && options.controlPlaneSyncPort && options.workspaceId) {
+    return wrapEventSubscriberWithControlPlaneSync(subscriber, {
+      controlPlaneSyncPort: options.controlPlaneSyncPort,
+      workspaceId: options.workspaceId,
+      pollIntervalMs: options.controlPlaneSyncIntervalMs ?? DEFAULT_CONTROL_PLANE_SYNC_INTERVAL_MS,
+      logger: options.controlPlaneDiagnosticsLogger,
+    });
+  }
+
+  return subscriber;
+}
+
+class CapturedResponse {
+  public statusCode = 200;
+  public body = '';
+  private readonly headers = new Map<string, string>();
+
+  public setHeader(name: string, value: string | number | readonly string[]): this {
+    this.headers.set(name.toLowerCase(), String(value));
+    return this;
+  }
+
+  public write(chunk: string | Buffer): boolean {
+    this.body += Buffer.isBuffer(chunk) ? chunk.toString('utf8') : chunk;
+    return true;
+  }
+
+  public end(chunk?: string | Buffer): this {
+    if (chunk !== undefined) {
+      this.write(chunk);
+    }
+    return this;
+  }
+
+  public toResult(): QueuedToolDispatchResult {
+    try {
+      return {
+        statusCode: this.statusCode,
+        body: this.body.length > 0 ? JSON.parse(this.body) : {},
+        headers: Object.fromEntries(this.headers.entries()),
+      };
+    } catch {
+      return {
+        statusCode: this.statusCode,
+        body: this.body,
+        headers: Object.fromEntries(this.headers.entries()),
+      };
+    }
+  }
+}
+
+function createQueuedToolDispatchRequest(input: QueuedToolDispatchRequest): IncomingMessage {
+  const request = new PassThrough() as unknown as IncomingMessage & {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+  };
+  request.method = HTTP_METHOD_POST;
+  request.url = `/tools/${encodeURIComponent(input.tool_name)}`;
+  request.headers = {
+    [HEADER_CONTENT_TYPE]: CONTENT_TYPE_JSON,
+  };
+  (request as unknown as PassThrough).end(
+    JSON.stringify({
+      input: input.input ?? {},
+      context: input.context,
+    }),
+  );
+  return request;
+}
+
+async function dispatchQueuedToolCommandWithRouter(
+  toolApiRouter: ToolApiRouter | undefined,
+  input: QueuedToolDispatchRequest,
+): Promise<QueuedToolDispatchResult> {
+  if (!toolApiRouter) {
+    return {
+      statusCode: HTTP_STATUS_NOT_FOUND,
+      body: {
+        [RESPONSE_ERROR_KEY]: {
+          [RESPONSE_MESSAGE_KEY]:
+            'Queued command dispatch is unavailable because the HTTP tool surface is disabled.',
+        },
+      },
+      headers: {
+        [HEADER_CONTENT_TYPE]: CONTENT_TYPE_JSON,
+      },
+    };
+  }
+
+  const response = new CapturedResponse();
+  await toolApiRouter.handleRequest(
+    createQueuedToolDispatchRequest(input),
+    response as unknown as ServerResponse<IncomingMessage>,
+    [input.tool_name],
+  );
+  return response.toResult();
+}
+
+export async function dispatchQueuedToolCommandThroughHttpSurface(
+  surface: HttpSurface,
+  input: QueuedToolDispatchRequest,
+): Promise<QueuedToolDispatchResult> {
+  if (typeof surface.dispatchQueuedToolCommand === 'function') {
+    return surface.dispatchQueuedToolCommand(input);
+  }
+
+  const response = new CapturedResponse();
+  await surface.handleRequest(
+    createQueuedToolDispatchRequest(input),
+    response as unknown as ServerResponse<IncomingMessage>,
+  );
+  return response.toResult();
+}
+
+export function createHttpSurface(
+  runtime: KernelRuntime,
+  options: HttpSurfaceOptions = {},
+): HttpSurface {
+  const taskApiRouter = createTaskApiRouter(runtime);
+  const toolApiRouter = options.allowlistedTools
+    ? createToolApiRouter(runtime, { allowlistedTools: options.allowlistedTools })
+    : undefined;
+  const toolDiscoveryRouter: ToolDiscoveryRouter | undefined = options.toolCatalog
+    ? createToolDiscoveryRouter({
+        toolCatalog: options.toolCatalog,
+        surfacesVersion: options.surfacesVersion ?? DEFAULT_SURFACES_VERSION,
+        workspaceId: options.workspaceId ?? DEFAULT_WORKSPACE_ID,
+      })
+    : undefined;
+  const eventStreamRouter = createEventStreamRouter(resolveEventSubscriber(runtime, options));
+  const runAgentConfig = options.workspaceId ? { workspaceId: options.workspaceId } : undefined;
+  const runAgentRouter = createRunAgentRouter(
+    runtime,
+    resolveEventSubscriber(runtime, options),
+    runAgentConfig,
+  );
+
+  return {
+    async dispatchQueuedToolCommand(
+      input: QueuedToolDispatchRequest,
+    ): Promise<QueuedToolDispatchResult> {
+      return dispatchQueuedToolCommandWithRouter(toolApiRouter, input);
+    },
+    async handleRequest(
+      request: IncomingMessage,
+      response: ServerResponse<IncomingMessage>,
+    ): Promise<void> {
+      const route = parseRoute(request);
+      const rootSegment = route.segments[0] ?? '';
+      const nestedSegments = route.segments.slice(1);
+
+      if (rootSegment === ROUTE_SEGMENT.TASKS) {
+        await taskApiRouter.handleRequest(request, response, nestedSegments);
+        return;
+      }
+
+      if (rootSegment === ROUTE_SEGMENT.TOOLS) {
+        // Root-level /tools (no nested segments): discovery owns the route
+        // (GET + 405 for other methods) whenever a toolCatalog is registered.
+        if (toolDiscoveryRouter && nestedSegments.length === 0) {
+          await toolDiscoveryRouter.handleRequest(request, response, nestedSegments);
+          return;
+        }
+        if (toolApiRouter) {
+          await toolApiRouter.handleRequest(request, response, nestedSegments);
+          return;
+        }
+      }
+
+      if (rootSegment === ROUTE_SEGMENT.EVENTS) {
+        await eventStreamRouter.handleRequest(
+          request,
+          response,
+          nestedSegments,
+          route.searchParams,
+        );
+        return;
+      }
+
+      if (matchesRunAgentRoute(route.segments)) {
+        await runAgentRouter.handleRequest(request, response);
+        return;
+      }
+
+      writeNotFound(response);
+    },
+  };
+}

package/http/sidecar-entry.ts

@@ -0,0 +1,218 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * WU-2642 (INIT-057 Phase 4): Sidecar entry for control-plane event sync.
+ *
+ * ADR-058 decided that between wu:claim and wu:done the control plane needs
+ * sub-minute visibility into durable state changes. `createHttpSurface` already
+ * wraps event emission with `wrapEventSubscriberWithControlPlaneSync`, but CLI
+ * sessions don't boot the HTTP surface. This module exposes a sidecar entry
+ * point that reuses the same sync-port contract **without** importing
+ * server.ts / createHttpSurface — making it cheap to spawn from wu:claim.
+ *
+ * @module sidecar-entry
+ */
+
+import type { KernelEvent } from '@lumenflow/kernel';
+import {
+  DEFAULT_CONTROL_PLANE_SYNC_INTERVAL_MS,
+  type ControlPlaneSyncPortLike,
+} from './control-plane-event-subscriber.js';
+
+const CONTROL_PLANE_POLICY_DECISION_DENY = 'deny';
+const WORKSPACE_WARNING_EVENT_KIND = 'workspace_warning';
+const KERNEL_EVENT_SCHEMA_VERSION = 1;
+const CLOCK_ISO_OFFSET = 36;
+const SYNC_SESSION_ID_PREFIX = 'sidecar-sync';
+const ACTIONABLE_SYNC_DIAGNOSTIC_SUFFIX = 'Check control_plane.endpoint and auth token.';
+
+const DIAGNOSTIC_REASON = {
+  POLICY_PULL_FAILED: 'policy pull failed',
+  HEARTBEAT_FAILED: 'heartbeat failed',
+  EVENT_PUSH_FAILED: 'event forwarding failed',
+} as const;
+
+export interface StartControlPlaneEventSyncOptions {
+  controlPlaneSyncPort: ControlPlaneSyncPortLike;
+  workspaceId: string;
+  /** Poll cadence. Defaults to {@link DEFAULT_CONTROL_PLANE_SYNC_INTERVAL_MS} when 0/undefined. */
+  syncIntervalMs?: number;
+  logger?: Pick<Console, 'warn'>;
+  /** Override for deterministic tests. */
+  now?: () => Date;
+}
+
+export interface ControlPlaneEventSyncHandle {
+  /** Enqueue a kernel event for the next sync cycle. */
+  enqueue(event: KernelEvent): void;
+  /** Stop the interval timer and release any resources. */
+  dispose(): void;
+}
+
+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(
+  pendingEvents: KernelEvent[],
+  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);
+  pendingEvents.push(createWorkspaceWarningEvent(message, now));
+}
+
+async function runSyncCycle(
+  options: Required<
+    Pick<StartControlPlaneEventSyncOptions, 'controlPlaneSyncPort' | 'workspaceId'>
+  > &
+    Pick<StartControlPlaneEventSyncOptions, 'logger'>,
+  sessionId: string,
+  pendingEvents: KernelEvent[],
+  state: SyncState,
+  now: () => Date,
+): Promise<void> {
+  if (state.inFlight) {
+    return;
+  }
+  state.inFlight = true;
+
+  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(
+        pendingEvents,
+        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(
+        pendingEvents,
+        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(
+        pendingEvents,
+        options.logger,
+        options.workspaceId,
+        DIAGNOSTIC_REASON.EVENT_PUSH_FAILED,
+        now,
+      );
+    }
+  } finally {
+    state.inFlight = false;
+  }
+}
+
+/**
+ * Start the control-plane event sync sidecar.
+ *
+ * Returns a handle whose `enqueue(event)` buffers kernel events that will be
+ * forwarded on the next sync cycle, and whose `dispose()` stops the interval
+ * timer. Call `dispose()` on wu:done / session-end to avoid leaking handles.
+ *
+ * Unlike `createHttpSurface`, this entry does not boot routers, task API, or
+ * the event-stream SSE pipeline. It only needs a
+ * {@link ControlPlaneSyncPortLike}.
+ */
+export function startControlPlaneEventSync(
+  options: StartControlPlaneEventSyncOptions,
+): ControlPlaneEventSyncHandle {
+  const intervalMs =
+    options.syncIntervalMs && options.syncIntervalMs > 0
+      ? options.syncIntervalMs
+      : DEFAULT_CONTROL_PLANE_SYNC_INTERVAL_MS;
+
+  const now = options.now ?? (() => new Date());
+  const sessionId = createSyncSessionId(now);
+  const pendingEvents: KernelEvent[] = [];
+  const state: SyncState = {
+    allowForwarding: true,
+    inFlight: false,
+  };
+
+  const timer = setInterval(() => {
+    void runSyncCycle(
+      {
+        controlPlaneSyncPort: options.controlPlaneSyncPort,
+        workspaceId: options.workspaceId,
+        logger: options.logger,
+      },
+      sessionId,
+      pendingEvents,
+      state,
+      now,
+    );
+  }, intervalMs);
+
+  // Don't block Node.js event loop from exiting in short-lived unit tests or
+  // one-shot CLI invocations that never call dispose().
+  if (typeof timer.unref === 'function') {
+    timer.unref();
+  }
+
+  return {
+    enqueue(event: KernelEvent): void {
+      pendingEvents.push(event);
+    },
+    dispose(): void {
+      clearInterval(timer);
+    },
+  };
+}
+
+export { DEFAULT_CONTROL_PLANE_SYNC_INTERVAL_MS };