yaml-flow 8.6.4 → 8.7.1

package/lib/server-runtime-core/index.d.ts

@@ -0,0 +1,378 @@
+import { d as BoardRuntimePlatformAdapter } from '../types-SO5OZm4s.js';
+export { A as Awaitable, B as BoardContextConfig, c as BoardRuntimeNonCorePublic, e as BoardRuntimePublic, C as ChatHandlerFlowRunner, D as DescribeEnvelope, H as HostedBoardQueueLaneTuning, I as InvocationAdapter, a as MultiBoardRuntime, M as MultiBoardRuntimeOptions, N as NotificationTransport, Q as QueueLaneRuntimeTuning, R as RuntimeLogger, f as RuntimeRequest, g as RuntimeResponse, b as SingleBoardRuntime, S as SingleBoardRuntimeOptions } from '../types-SO5OZm4s.js';
+export { HostedBoardQueueLaneRegistryOptions, createHostedBoardQueueLaneRegistry } from '../server-jobs-queue-runner/index.js';
+export { M as McpControlplaneRegistryDeps, a as McpFacadeForRegistry, b as McpWebhookFacadeForRegistry, T as ToolRegistry, c as createMcpControlplaneToolRegistry, d as createMcpToolRegistry, e as createMcpWebhookToolRegistry } from '../mcp-tool-registries-BBObLYga.js';
+import { createBoardLiveCardsMcp, BoardLiveCardsMcpBoardDeps, BoardLiveCardsMcpNonCoreDeps, BoardLiveCardsMcpCardStoreDeps, BoardLiveCardsMcp } from '../board-live-cards-mcp.js';
+import { a as CommandResult } from '../board-live-cards-public-JNRKfBZy.js';
+export { B as BoardChangeNotification, c as BoardLiveCardsPublic, d as BoardNonCorePlatformAdapter, e as BoardPlatformAdapter, f as BoardWorkerRequest, C as CommandInput } from '../board-live-cards-public-JNRKfBZy.js';
+import { C as CardFileMetadataStore } from '../artifacts-store-lib-DSSMqVL2.js';
+import { A as AsyncBoardPlatformAdapter } from '../board-platform-adapter-async-DYahVzIK.js';
+import { ExecutionRef } from '../execution-refs.js';
+export { A as AsyncBoardLiveCardsPublic } from '../board-live-cards-public-async-fwd1QI82.js';
+export { B as BlobStorage, K as KVStorage, a as KindValueRef } from '../storage-interface-BFiD3kyB.js';
+export { C as ChatStorage } from '../chat-storage-lib-DB9iSai2.js';
+import '../queue-lane-registry-PaZuFpwp.js';
+import '../chat-store-public.js';
+import '../types-BBhqYGhE.js';
+import '../storage-async-interface-DhlOVPSp.js';
+
+/**
+ * server-runtime/notifications.ts
+ *
+ * Per-board notification accumulator state and the small set of pure helpers
+ * that fold incoming runtime events into that state. Owned by the runtime
+ * closure; no I/O.
+ */
+interface NotificationState {
+    status: unknown;
+    computedValues: Record<string, unknown>;
+    dataObjects: Record<string, unknown>;
+    cards: Record<string, unknown>;
+}
+declare function makeNotificationState(): NotificationState;
+declare function hasNonEmptyCardCountStatus(status: unknown): boolean;
+declare function appendNotification(state: NotificationState, event: unknown): void;
+
+/**
+ * server-runtime/mcp-invoker.ts
+ *
+ * Pure helpers for invoking MCP tools through a registry and turning a tool
+ * result into a human-readable error message. Both helpers are platform-free
+ * and depend only on plain values — no closure state.
+ */
+type McpToolHandler = (args: Record<string, unknown>) => unknown | Promise<unknown>;
+type McpToolRegistry = Record<string, McpToolHandler>;
+/**
+ * Look up `tool` in `registry` and invoke it with `args`. Normalises the
+ * returned shape so callers always see `{ status, data? }` (or an explicit
+ * `fail` / `error` envelope). Throws an Error tagged with `statusCode: 400`
+ * if the tool is unknown.
+ */
+declare function invokeMcpTool(tool: string, args: Record<string, unknown>, registry: McpToolRegistry): Promise<unknown>;
+/**
+ * Extract a single human-readable failure message from an MCP tool result,
+ * looking through validation envelopes for the first useful issue string.
+ * Returns `fallback` when nothing better can be found.
+ */
+declare function extractMcpFailureMessage(result: unknown, fallback: string): string;
+
+/**
+ * server-runtime/mcp-args.ts
+ *
+ * Pure MCP tool argument parsers. These read from the args record and do not
+ * touch runtime state. Kept here so the index closure does not redefine them.
+ */
+declare function getMcpArgString(args: Record<string, unknown>, ...keys: string[]): string;
+declare function getMcpArgNumber(args: Record<string, unknown>, ...keys: string[]): number | undefined;
+declare function getMcpArgRecord(args: Record<string, unknown>, ...keys: string[]): Record<string, unknown>;
+declare function getRequiredMcpArgRecord(args: Record<string, unknown>, errorKey: string, ...keys: string[]): Record<string, unknown>;
+declare function getRequiredMcpArgNumber(args: Record<string, unknown>, errorKey: string, ...keys: string[]): number;
+declare function parseMcpUploadBytes(args: Record<string, unknown>): Uint8Array | null;
+
+/**
+ * server-runtime/mcp-facade.ts
+ *
+ * MCP facade wiring extracted from createSingleBoardServerRuntime.
+ * Builds the four facade pieces used by the per-board MCP entry point:
+ * - mcpBoardFacade        (board command surface used by MCP)
+ * - mcpNonCoreFacade      (preflight / discovery surface)
+ * - mcpCardStoreFacade    (card-store CRUD surface)
+ * - createMcpFacade       (composes the above into BoardLiveCardsMcp)
+ *
+ * The facade reaches into many runtime closures (status snapshots,
+ * data-object reads, card-store reads, lane drains, etc.). Those are
+ * passed in as narrow callbacks so this module stays portable.
+ */
+
+/** Subset of BoardContext consumed by the facade. */
+interface McpFacadeBoardContextLike {
+    boardAdapter: unknown;
+    boardOps: {
+        getOutputsFetchedSources: (input: {
+            params: {
+                key: string;
+            };
+        }) => Promise<CommandResult>;
+        removeCard: (input: {
+            params: {
+                id: string;
+            };
+        }) => Promise<CommandResult>;
+        cardRefreshedNotify: (input: {
+            params: {
+                cardId: string;
+            };
+        }) => Promise<CommandResult>;
+        upsertCard: (input: {
+            params: {
+                cardId: string;
+                restart: boolean;
+            };
+        }) => Promise<CommandResult>;
+    };
+    cardStoreOps: {
+        set: (input: {
+            body: unknown;
+        }) => Promise<CommandResult>;
+        del: (input: {
+            params: {
+                id: string;
+            };
+        }) => Promise<CommandResult>;
+        patch: (input: {
+            params?: {
+                id?: string;
+                path?: string;
+            };
+            body?: unknown;
+        }) => Promise<CommandResult>;
+        appendFiles: (input: {
+            params?: {
+                id?: string;
+            };
+            body?: unknown;
+        }) => Promise<CommandResult>;
+    };
+    nonCore: {
+        describeTaskExecutorCapabilities: (input: unknown) => unknown;
+        validateCardPreflight: (input: unknown) => unknown;
+        evalCardCompute: (input: unknown) => unknown;
+        probeSourcePreflight: (input: unknown) => unknown;
+        runSourcePreflight: (input: unknown) => unknown;
+        simulateCardCycle: (input: unknown) => unknown;
+    } | null;
+}
+interface McpFacadeDeps {
+    boardContexts: ReadonlyArray<McpFacadeBoardContextLike>;
+    cardOwnerIndex: Map<string, number>;
+    cardContextForCard: (cardId: string) => McpFacadeBoardContextLike | null;
+    readStatusSnapshot: () => Promise<unknown>;
+    readDataObjectsByToken: () => Promise<Record<string, unknown>>;
+    readCardRuntimeArtifacts: () => Promise<Record<string, unknown>>;
+    readCardFromStore: (cardId: string) => Promise<Record<string, unknown> | null>;
+    readCardDefinitions: () => Promise<unknown[]>;
+    processAccumulatedLaneInternal: (skipInit?: boolean) => Promise<CommandResult>;
+    reportSourceFetched: (token: string, ref: string) => Promise<CommandResult>;
+    reportSourceFetchFailure: (token: string, reason: string) => Promise<CommandResult>;
+    uploadCardFile: (cardId: string, fileName: string, contentType: string, bytes: Uint8Array, opts?: {
+        inChat?: boolean;
+        suppressChatRecordWrite?: boolean;
+    }) => unknown | Promise<unknown>;
+    chatStorePublic: Parameters<typeof createBoardLiveCardsMcp>[0]['chatStore'];
+    serverUrl: string | null;
+    apiBasePath: string;
+}
+interface McpFacadeModule {
+    mcpBoardFacade: () => BoardLiveCardsMcpBoardDeps;
+    mcpNonCoreFacade: () => BoardLiveCardsMcpNonCoreDeps;
+    mcpCardStoreFacade: () => BoardLiveCardsMcpCardStoreDeps;
+    createMcpFacade: () => BoardLiveCardsMcp;
+}
+declare function createMcpFacadeModule(deps: McpFacadeDeps): McpFacadeModule;
+
+/**
+ * server-runtime/runtime-payload.ts
+ *
+ * Read-only aggregation of the per-runtime "published" payload that SSE
+ * snapshots and the /board-status endpoint return. Pulled out of
+ * createSingleBoardServerRuntime so the closure no longer has to host the
+ * three readers (status, computed-values, data-objects) plus the published
+ * payload assembler.
+ *
+ * Uses a structural board-context type with only the fields the readers need,
+ * so this module doesn't pull in the heavy BoardContext interface from
+ * index.ts.
+ */
+
+/** Minimum surface of the kv-storage handle used to read persisted status. */
+interface KvStorageReader {
+    read(key: string): unknown | Promise<unknown>;
+}
+/** Minimum surface of the board-platform adapter consumed by readStatusSnapshot. */
+interface BoardAdapterForPayload {
+    kvStorageForRef(ref: string): KvStorageReader;
+}
+/** Minimum surface of the board-ops handle consumed by payload readers. */
+interface BoardOpsForPayload {
+    getAllOutputsComputedValues(input: Record<string, unknown>): {
+        status: string;
+        data?: unknown;
+    } | Promise<{
+        status: string;
+        data?: unknown;
+    }>;
+    getAllOutputsDataObjects(input: Record<string, unknown>): {
+        status: string;
+        data?: unknown;
+    } | Promise<{
+        status: string;
+        data?: unknown;
+    }>;
+}
+/** Subset of BoardContext consumed by runtime-payload readers. */
+interface RuntimePayloadBoardContext {
+    boardOps: BoardOpsForPayload;
+    boardAdapter: BoardAdapterForPayload;
+    outputsStoreRef: string;
+    notification: NotificationState;
+}
+interface RuntimePayloadDeps {
+    boardId: string;
+    /** Live reference to the runtime's board-contexts array (read on each call). */
+    boardContexts: ReadonlyArray<RuntimePayloadBoardContext>;
+    readCardDefinitions: () => Promise<Array<Record<string, unknown>>>;
+    readChatRecords: (cardId: string) => Array<Record<string, unknown>>;
+    getChatProcessing: (cardId: string) => boolean;
+}
+interface RuntimePayloadModule {
+    readStatusSnapshot: () => Promise<unknown>;
+    readCardRuntimeArtifacts: () => Promise<Record<string, unknown>>;
+    readDataObjectsByToken: () => Promise<Record<string, unknown>>;
+    buildPublishedRuntimePayload: () => Promise<unknown>;
+}
+declare function createRuntimePayloadModule(deps: RuntimePayloadDeps): RuntimePayloadModule;
+
+/**
+ * server-runtime/controlplane-tool-handlers.ts
+ *
+ * Handlers for the small "controlplane" MCP tools that read/write chat
+ * processing state and per-card meta. Each handler validates `board_id`
+ * against the runtime's own boardId, requires `card_id`, then delegates to
+ * the MCP facade or card-store facade supplied by the host runtime.
+ *
+ * The handlers are factored out of createSingleBoardServerRuntime so that
+ * createMcpControlplaneToolRegistry in index.ts can simply wire them up,
+ * keeping the closure free of repetitive arg-validation noise.
+ */
+
+interface ControlplaneToolHandlersDeps {
+    boardId: string;
+    /** Returns the live MCP facade (chat processing getters/setters). */
+    getMcpFacade: () => {
+        setChatProcessing: (args: {
+            cardId: string;
+            active: boolean;
+        }) => unknown;
+        getChatProcessing: (args: {
+            cardId: string;
+        }) => {
+            active: boolean;
+        };
+    };
+    /** Returns the card-store facade used for meta reads/writes. */
+    getMcpCardStoreFacade: () => BoardLiveCardsMcpCardStoreDeps;
+}
+interface ControlplaneToolHandlers {
+    requireCardArgs: (args: Record<string, unknown>) => {
+        cardId: string;
+    };
+    setChatProcessing: (args: Record<string, unknown>, active: boolean) => {
+        status: 'success';
+        data: {
+            boardId: string;
+            cardId: string;
+            active: boolean;
+        };
+    };
+    getChatProcessing: (args: Record<string, unknown>) => {
+        status: 'success';
+        data: {
+            boardId: string;
+            cardId: string;
+            active: boolean;
+        };
+    };
+    setCardMeta: (args: Record<string, unknown>) => Promise<{
+        status: 'success';
+        data: {
+            boardId: string;
+            cardId: string;
+            key: string;
+        };
+    }>;
+    getCardMeta: (args: Record<string, unknown>) => Promise<{
+        status: 'success';
+        data: {
+            boardId: string;
+            cardId: string;
+            key: string;
+            exists: boolean;
+            value: unknown;
+        };
+    }>;
+}
+declare function createControlplaneToolHandlers(deps: ControlplaneToolHandlersDeps): ControlplaneToolHandlers;
+
+/**
+ * server-runtime/controlplane-helpers.ts
+ *
+ * Pure helpers used by the runtime's controlplane MCP handlers. The handlers
+ * themselves still live in index.ts because they capture closure state; these
+ * utilities are stateless.
+ */
+
+declare function expectControlplaneSuccess<T>(result: CommandResult<T>, commandName: string): T;
+declare function expectControlplaneSuccessAsync<T>(result: CommandResult<T> | Promise<CommandResult<T>>, commandName: string): Promise<T>;
+declare function getCardMetaKey(args: Record<string, unknown>): string;
+declare function readCardMetaValue(card: Record<string, unknown>, key: string): {
+    exists: boolean;
+    value: unknown;
+};
+
+/**
+ * server-runtime/card-file-ops.ts
+ *
+ * Per-card file upload / metadata-merge orchestration extracted from
+ * createSingleBoardServerRuntime. The factory takes narrow callbacks for
+ * the small handful of closure-owned helpers (card-store reads,
+ * card-data writes, chat-record writes, artifact stores, file-metadata
+ * normaliser) and exposes the upload entry point plus its read helper.
+ */
+
+/** Subset of the per-card files artifact store consumed by file-ops. */
+interface FilesArtifactsStoreLike {
+    putBytes(key: string, content: Uint8Array, contentType?: string): unknown | Promise<unknown>;
+}
+interface CardFileOpsDeps {
+    /** Sanitised card-id suitable for use as a storage prefix. */
+    safeCardId: (cardId: string) => string;
+    /** Returns the per-card artifact stores; `files` is the bytes sink. */
+    artifactsStores: (cardId: string) => {
+        files: FilesArtifactsStoreLike | null;
+    };
+    /** Card-file-metadata store wired against the runtime's persistence layer. */
+    cardFileMetadataStore: () => CardFileMetadataStore;
+    /** Read the persisted card from the store (used to count existing files). */
+    readCardFromStore: (cardId: string) => Promise<Record<string, unknown> | null>;
+    /** Apply a local-only update to a card; same shape as updateCardLocalOnly. */
+    updateCardLocalOnly: (cardId: string, updateFn: (card: Record<string, unknown>) => Record<string, unknown> | void) => Promise<void>;
+    /** Append a chat record (used for in-chat upload announcements). */
+    writeChatRecord: (cardId: string, role: string, text: string, files: unknown[], turnId: string) => unknown;
+}
+interface CardFileOps {
+    uploadCardFile: (cardId: string, requestedName: string, contentType: string, buffer: Uint8Array, opts?: {
+        inChat?: boolean;
+        turnId?: string;
+        suppressChatRecordWrite?: boolean;
+    }) => Promise<{
+        ok: true;
+        file: Record<string, unknown>;
+    }>;
+    readCardStoredFileNames: (cardId: string) => Promise<string[]>;
+}
+declare function createCardFileOps(deps: CardFileOpsDeps): CardFileOps;
+
+/**
+ * server-runtime/internal-helpers.ts
+ *
+ * Small, pure helpers shared across the server-runtime slices. No closure
+ * state, no I/O. Anything that depends on runtime state belongs in a slice
+ * module, not here.
+ */
+
+declare function isAsyncBoardPlatformAdapter(adapter: BoardRuntimePlatformAdapter): adapter is AsyncBoardPlatformAdapter;
+declare function executionWhatToRunValue(ref: ExecutionRef): string;
+declare function escapeRegExp(str: string): string;
+declare function concatUint8Arrays(arrays: Uint8Array[]): Uint8Array;
+
+export { AsyncBoardPlatformAdapter, BoardRuntimePlatformAdapter, CommandResult, ExecutionRef, type McpFacadeBoardContextLike, type McpFacadeDeps, type McpFacadeModule, type McpToolHandler, type McpToolRegistry, type NotificationState, type RuntimePayloadBoardContext, type RuntimePayloadDeps, type RuntimePayloadModule, appendNotification, concatUint8Arrays, createCardFileOps, createControlplaneToolHandlers, createMcpFacadeModule, createRuntimePayloadModule, escapeRegExp, executionWhatToRunValue, expectControlplaneSuccess, expectControlplaneSuccessAsync, extractMcpFailureMessage, getCardMetaKey, getMcpArgNumber, getMcpArgRecord, getMcpArgString, getRequiredMcpArgNumber, getRequiredMcpArgRecord, hasNonEmptyCardCountStatus, invokeMcpTool, isAsyncBoardPlatformAdapter, makeNotificationState, parseMcpUploadBytes, readCardMetaValue };

package/lib/server-runtime-core/index.js

@@ -0,0 +1,2 @@
+export{c as appendNotification,j as createCardFileOps,h as createControlplaneToolHandlers,m as createMcpControlplaneToolRegistry,n as createMcpFacadeModule,k as createMcpToolRegistry,l as createMcpWebhookToolRegistry,i as createRuntimePayloadModule,d as expectControlplaneSuccess,e as expectControlplaneSuccessAsync,f as getCardMetaKey,b as hasNonEmptyCardCountStatus,a as makeNotificationState,g as readCardMetaValue}from'../chunk-QJVR3FWQ.js';export{b as getMcpArgNumber,c as getMcpArgRecord,a as getMcpArgString,e as getRequiredMcpArgNumber,d as getRequiredMcpArgRecord,f as parseMcpUploadBytes}from'../chunk-O7NOHKVR.js';export{d as concatUint8Arrays,c as escapeRegExp,b as executionWhatToRunValue,a as isAsyncBoardPlatformAdapter}from'../chunk-SGV7PU4H.js';export{b as extractMcpFailureMessage,a as invokeMcpTool}from'../chunk-ZJ5M5COT.js';export{a as createHostedBoardQueueLaneRegistry}from'../chunk-YGALANRO.js';import'../chunk-VXJHBWK3.js';import'../chunk-BQS3EIEK.js';import'../chunk-ZCNN6XPV.js';import'../chunk-JMDHDY6M.js';import'../chunk-3KC6LBOG.js';import'../chunk-MNEOJWPS.js';import'../chunk-FW4363Y4.js';//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/lib/server-runtime-watchers/index.cjs

@@ -0,0 +1,2 @@
+'use strict';var chunk7ICPAABP_cjs=require('../chunk-7ICPAABP.cjs');require('../chunk-KAWQPLIE.cjs'),require('../chunk-SFVO2LB2.cjs'),require('../chunk-GNFE24S7.cjs');Object.defineProperty(exports,"createRoutesWatchers",{enumerable:true,get:function(){return chunk7ICPAABP_cjs.b}});Object.defineProperty(exports,"createSseHub",{enumerable:true,get:function(){return chunk7ICPAABP_cjs.a}});//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/lib/server-runtime-watchers/index.d.cts

@@ -0,0 +1,127 @@
+import { g as RuntimeResponse, f as RuntimeRequest } from '../types-Ba8H5_Wo.cjs';
+import { C as ChatStorage } from '../chat-storage-lib-B9Q34Dyv.cjs';
+import '../artifacts-store-lib-D9nMkVcE.cjs';
+import '../storage-interface-BFiD3kyB.cjs';
+import '../board-live-cards-public-LlVUQPL2.cjs';
+import '../execution-refs.cjs';
+import '../types-BBhqYGhE.cjs';
+import '../board-platform-adapter-async-BfHmHdx2.cjs';
+import '../storage-async-interface-BRR4eBjx.cjs';
+import '../board-live-cards-public-async-Di9QB141.cjs';
+
+/**
+ * server-runtime/sse-hub.ts
+ *
+ * Owns the per-runtime SSE client registry, the chat-subscription scanner, and
+ * all broadcast helpers. The HTTP route handler for the SSE endpoint still
+ * lives in index.ts because it sequences SSE registration with runtime
+ * bootstrap; this hub exposes the primitives it needs.
+ *
+ * State owned here:
+ *   - sseClients (clientId -> { res, subscribedChatCardIds })
+ *   - sseEventId monotonic counter
+ *   - chat-subscription scan timer + per-card cursor/processing snapshots
+ *
+ * Dependencies passed in by the runtime:
+ *   - chatStorage for tailing chat history
+ *   - readChatRecords for building chat-scoped notifications
+ *   - optional host hooks (onSseClientDisconnected, etc.)
+ */
+
+interface SseClientState {
+    res: RuntimeResponse;
+    subscribedChatCardIds: Set<string>;
+}
+interface SseHub {
+    /** Number of currently-registered SSE clients. */
+    size(): number;
+    /** Whether a client id is currently registered. */
+    has(clientId: string): boolean;
+    /** Returns the existing client state if present (used to migrate chat subs on reconnect). */
+    get(clientId: string): SseClientState | undefined;
+    /** Build a wire-format SSE frame for the given payload. Increments the event id. */
+    buildFrame(payload: unknown): string;
+    /** Best-effort transport-level flush for the underlying response object. */
+    flushTransport(res: RuntimeResponse): void;
+    /** Register a fresh client. Any prior registration with the same id is disconnected first. */
+    register(clientId: string, res: RuntimeResponse, subscribedChatCardIds?: Set<string>): void;
+    /** Drop a registered client. If expectedRes is supplied and does not match, no-op. */
+    disconnect(clientId: string, expectedRes?: RuntimeResponse): void;
+    /** Write an SSE frame to one client; transport errors disconnect that client. */
+    writeFrame(clientId: string, payload: unknown): void;
+    /** Subscribe a client to a card's chat stream and prime its cursor. */
+    subscribeChat(clientId: string, cardId: string): boolean;
+    /** Unsubscribe a client from a card's chat stream. */
+    unsubscribeChat(clientId: string, cardId: string): boolean;
+    /** Broadcast a notification batch; chat-scoped notes are routed to chat-subscribed clients. */
+    broadcastNotificationBatch(notifications: unknown[]): void;
+    /** Push a fresh card-chats notification to every chat-subscribed client. */
+    broadcastCardChats(cardId: string, receiving?: boolean): void;
+}
+interface SseHubDeps {
+    chatStorage: ChatStorage;
+    readChatRecords: (cardId: string) => Array<Record<string, unknown>>;
+    onSseClientDisconnected?: (clientId: string) => void;
+}
+declare function createSseHub(deps: SseHubDeps): SseHub;
+
+/**
+ * server-runtime/routes-sse.ts
+ *
+ * SSE connection lifecycle handler and channel-subscription endpoint
+ * extracted from createSingleBoardServerRuntime. Both functions are
+ * stateless wrappers around sseHub + the runtime payload aggregator;
+ * factory takes narrow callbacks for everything else.
+ */
+
+interface RoutesSseDeps {
+    sseHub: SseHub;
+    corsHeaders: Record<string, string>;
+    json: (res: RuntimeResponse, status: number, payload: unknown) => void;
+    buildPublishedRuntimePayload: () => Promise<unknown>;
+    onSseClientConnected?: (clientId: string, writeFrame: (payload: unknown) => void) => void;
+    onChannelSubscribed?: (clientId: string, channelName: string, params: {
+        cardId?: string;
+    }) => void;
+    onChannelUnsubscribed?: (clientId: string, channelName: string, params: {
+        cardId?: string;
+    }) => void;
+}
+
+/**
+ * server-runtime/routes-watchers.ts
+ *
+ * All SSE connection and subscription management routes.
+ * This is the sole owner of sseHub from a routing perspective.
+ *
+ *   GET  /sse                                             — open SSE stream
+ *   POST /cards/:id/chats/(un)subscribe-sse               — chat subscription
+ *   POST /watch-channel/:name/(un)subscribe-sse           — board channel
+ *   POST /cards/:id/watch-channel/:name/(un)subscribe-sse — card channel
+ *
+ * Composes createRoutesSse for the SSE connection primitives and adds
+ * the HTTP subscription management endpoints on top.
+ */
+
+interface RoutesWatchersDeps extends RoutesSseDeps {
+    apiBasePath: string;
+    readJsonBody: (req: RuntimeRequest) => Promise<Record<string, unknown>>;
+    initBoardAndSetup: () => Promise<void>;
+    bootstrapBoard: () => Promise<void>;
+    boardContexts: ReadonlyArray<unknown>;
+    publishPersistedStateSnapshot: (ctx: unknown) => Promise<void>;
+    upsertCardsFromSource: (ctx: unknown, ctxIndex: number) => Promise<void>;
+}
+interface RoutesWatchers {
+    /** Dispatch SSE + subscription routes. Returns true if the request was handled. */
+    handleWatchersRoutes: (req: RuntimeRequest, res: RuntimeResponse, parsedUrl: URL) => Promise<boolean>;
+    /** Open an SSE stream for a client (also used by the legacy handleRuntimeApi delegate). */
+    handleSse: (req: RuntimeRequest, res: RuntimeResponse, clientId: string) => Promise<void>;
+    /** Subscribe or unsubscribe a client from a named channel. */
+    handleChannelSubscription: (res: RuntimeResponse, clientId: string, channelName: string, params: {
+        cardId?: string;
+    }, subscribed: boolean) => void;
+}
+declare function createRoutesWatchers(deps: RoutesWatchersDeps): RoutesWatchers;
+
+export { type RoutesWatchers, type RoutesWatchersDeps, type SseHub, type SseHubDeps, createRoutesWatchers, createSseHub };

package/lib/server-runtime-watchers/index.d.ts

@@ -0,0 +1,127 @@
+import { g as RuntimeResponse, f as RuntimeRequest } from '../types-SO5OZm4s.js';
+import { C as ChatStorage } from '../chat-storage-lib-DB9iSai2.js';
+import '../artifacts-store-lib-DSSMqVL2.js';
+import '../storage-interface-BFiD3kyB.js';
+import '../board-live-cards-public-JNRKfBZy.js';
+import '../execution-refs.js';
+import '../types-BBhqYGhE.js';
+import '../board-platform-adapter-async-DYahVzIK.js';
+import '../storage-async-interface-DhlOVPSp.js';
+import '../board-live-cards-public-async-fwd1QI82.js';
+
+/**
+ * server-runtime/sse-hub.ts
+ *
+ * Owns the per-runtime SSE client registry, the chat-subscription scanner, and
+ * all broadcast helpers. The HTTP route handler for the SSE endpoint still
+ * lives in index.ts because it sequences SSE registration with runtime
+ * bootstrap; this hub exposes the primitives it needs.
+ *
+ * State owned here:
+ *   - sseClients (clientId -> { res, subscribedChatCardIds })
+ *   - sseEventId monotonic counter
+ *   - chat-subscription scan timer + per-card cursor/processing snapshots
+ *
+ * Dependencies passed in by the runtime:
+ *   - chatStorage for tailing chat history
+ *   - readChatRecords for building chat-scoped notifications
+ *   - optional host hooks (onSseClientDisconnected, etc.)
+ */
+
+interface SseClientState {
+    res: RuntimeResponse;
+    subscribedChatCardIds: Set<string>;
+}
+interface SseHub {
+    /** Number of currently-registered SSE clients. */
+    size(): number;
+    /** Whether a client id is currently registered. */
+    has(clientId: string): boolean;
+    /** Returns the existing client state if present (used to migrate chat subs on reconnect). */
+    get(clientId: string): SseClientState | undefined;
+    /** Build a wire-format SSE frame for the given payload. Increments the event id. */
+    buildFrame(payload: unknown): string;
+    /** Best-effort transport-level flush for the underlying response object. */
+    flushTransport(res: RuntimeResponse): void;
+    /** Register a fresh client. Any prior registration with the same id is disconnected first. */
+    register(clientId: string, res: RuntimeResponse, subscribedChatCardIds?: Set<string>): void;
+    /** Drop a registered client. If expectedRes is supplied and does not match, no-op. */
+    disconnect(clientId: string, expectedRes?: RuntimeResponse): void;
+    /** Write an SSE frame to one client; transport errors disconnect that client. */
+    writeFrame(clientId: string, payload: unknown): void;
+    /** Subscribe a client to a card's chat stream and prime its cursor. */
+    subscribeChat(clientId: string, cardId: string): boolean;
+    /** Unsubscribe a client from a card's chat stream. */
+    unsubscribeChat(clientId: string, cardId: string): boolean;
+    /** Broadcast a notification batch; chat-scoped notes are routed to chat-subscribed clients. */
+    broadcastNotificationBatch(notifications: unknown[]): void;
+    /** Push a fresh card-chats notification to every chat-subscribed client. */
+    broadcastCardChats(cardId: string, receiving?: boolean): void;
+}
+interface SseHubDeps {
+    chatStorage: ChatStorage;
+    readChatRecords: (cardId: string) => Array<Record<string, unknown>>;
+    onSseClientDisconnected?: (clientId: string) => void;
+}
+declare function createSseHub(deps: SseHubDeps): SseHub;
+
+/**
+ * server-runtime/routes-sse.ts
+ *
+ * SSE connection lifecycle handler and channel-subscription endpoint
+ * extracted from createSingleBoardServerRuntime. Both functions are
+ * stateless wrappers around sseHub + the runtime payload aggregator;
+ * factory takes narrow callbacks for everything else.
+ */
+
+interface RoutesSseDeps {
+    sseHub: SseHub;
+    corsHeaders: Record<string, string>;
+    json: (res: RuntimeResponse, status: number, payload: unknown) => void;
+    buildPublishedRuntimePayload: () => Promise<unknown>;
+    onSseClientConnected?: (clientId: string, writeFrame: (payload: unknown) => void) => void;
+    onChannelSubscribed?: (clientId: string, channelName: string, params: {
+        cardId?: string;
+    }) => void;
+    onChannelUnsubscribed?: (clientId: string, channelName: string, params: {
+        cardId?: string;
+    }) => void;
+}
+
+/**
+ * server-runtime/routes-watchers.ts
+ *
+ * All SSE connection and subscription management routes.
+ * This is the sole owner of sseHub from a routing perspective.
+ *
+ *   GET  /sse                                             — open SSE stream
+ *   POST /cards/:id/chats/(un)subscribe-sse               — chat subscription
+ *   POST /watch-channel/:name/(un)subscribe-sse           — board channel
+ *   POST /cards/:id/watch-channel/:name/(un)subscribe-sse — card channel
+ *
+ * Composes createRoutesSse for the SSE connection primitives and adds
+ * the HTTP subscription management endpoints on top.
+ */
+
+interface RoutesWatchersDeps extends RoutesSseDeps {
+    apiBasePath: string;
+    readJsonBody: (req: RuntimeRequest) => Promise<Record<string, unknown>>;
+    initBoardAndSetup: () => Promise<void>;
+    bootstrapBoard: () => Promise<void>;
+    boardContexts: ReadonlyArray<unknown>;
+    publishPersistedStateSnapshot: (ctx: unknown) => Promise<void>;
+    upsertCardsFromSource: (ctx: unknown, ctxIndex: number) => Promise<void>;
+}
+interface RoutesWatchers {
+    /** Dispatch SSE + subscription routes. Returns true if the request was handled. */
+    handleWatchersRoutes: (req: RuntimeRequest, res: RuntimeResponse, parsedUrl: URL) => Promise<boolean>;
+    /** Open an SSE stream for a client (also used by the legacy handleRuntimeApi delegate). */
+    handleSse: (req: RuntimeRequest, res: RuntimeResponse, clientId: string) => Promise<void>;
+    /** Subscribe or unsubscribe a client from a named channel. */
+    handleChannelSubscription: (res: RuntimeResponse, clientId: string, channelName: string, params: {
+        cardId?: string;
+    }, subscribed: boolean) => void;
+}
+declare function createRoutesWatchers(deps: RoutesWatchersDeps): RoutesWatchers;
+
+export { type RoutesWatchers, type RoutesWatchersDeps, type SseHub, type SseHubDeps, createRoutesWatchers, createSseHub };

package/lib/server-runtime-watchers/index.js

@@ -0,0 +1,2 @@
+export{b as createRoutesWatchers,a as createSseHub}from'../chunk-WHDEBJLT.js';import'../chunk-SGV7PU4H.js';import'../chunk-BQS3EIEK.js';import'../chunk-FW4363Y4.js';//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/lib/server-runtime-webhooks/index.cjs

@@ -0,0 +1,2 @@
+'use strict';var chunkNM6O35RY_cjs=require('../chunk-NM6O35RY.cjs');require('../chunk-272IYUKT.cjs'),require('../chunk-GNFE24S7.cjs');Object.defineProperty(exports,"createRoutesWebhooks",{enumerable:true,get:function(){return chunkNM6O35RY_cjs.a}});//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map