@skein-js/server-kit 0.11.2 → 0.12.0

package/README.md

@@ -2,7 +2,7 @@
 
 > Shared, framework-agnostic building blocks for skein-js HTTP adapters.
 
-Part of **[skein-js](../../README.md)** — a TypeScript [Agent Protocol](https://github.com/langchain-ai/agent-protocol) server for [LangGraph.js](https://github.com/langchain-ai/langgraphjs), and a drop-in replacement for the LangGraph CLI.
+Part of **[skein-js](../../README.md)** — the open-source alternative to LangGraph Platform for TypeScript: a self-hosted [Agent Protocol](https://github.com/langchain-ai/agent-protocol) server for [LangGraph.js](https://github.com/langchain-ai/langgraphjs), and a drop-in replacement for the LangGraph CLI.
 
 This package is the common ground the framework adapters ([`@skein-js/express`](../server-express),
 [`@skein-js/fastify`](../server-fastify), [`@skein-js/nestjs`](../server-nestjs),
@@ -24,8 +24,9 @@ handler table.
   `{ deps }` to any adapter. `overrides` swaps in production drivers/auth. See
   [docs/embedding.md](../../docs/embedding.md).
 - **LangGraph dev-state import** — `readLanggraphDevState` / `loadSnapshotIntoStore` /
-  `describeSnapshot`: read an existing `.langgraph_api/` directory and reconstruct skein's own
-  `DevStateSnapshot`, so adopting skein carries all local state over losslessly.
+  `describeSnapshot`, from the **`@skein-js/server-kit/dev` subpath**: read an existing
+  `.langgraph_api/` directory and reconstruct skein's own `DevStateSnapshot`, so adopting skein carries
+  all local state over losslessly.
 - **CORS** — `corsFromHttpConfig` / `toCorsOptions` map a `langgraph.json` `http.cors` block to
   `cors`-style `CorsOptions`; `allowedOrigin` / `corsResponseHeaders` / `applyNodeCors` /
   `sendNodePreflight` derive CORS headers for the adapters without a CORS middleware of their own
@@ -92,12 +93,39 @@ Pass `overrides` to swap in production drivers or an auth engine while keeping t
   `DEFAULT_RUN_CONCURRENCY` (10, matching the LangGraph CLI). The environment is validated even when
   an explicit value is given, so the two sources can't silently disagree. `skein dev`/`start` use it
   to resolve the number they print in the startup banner.
+- **`startHeapPressureMonitor(options): HeapPressureMonitor`** — samples `v8.getHeapStatistics()` on an
+  unref'd interval and warns **once per crossing** (85% of the heap limit, re-arming below 70%), with
+  in-flight runs and buffered frames alongside so the line distinguishes too-much-concurrency from a slow
+  SSE consumer from a leak. `resolveHeapPressureOptions()` reads `SKEIN_HEAP_WARN_PERCENT` (`0` disables)
+  and `SKEIN_HEAP_SAMPLE_MS`. Started by `resolveProtocolRuntime` and stopped with the worker, so no
+  adapter has to remember it. Free when no logger is configured — it schedules nothing.
+- **`checkHeapHeadroom(): HeapHeadroom`** — the boot-time counterpart: compares V8's ceiling with the
+  container's cgroup limit and warns when the automatic sizing does not fit (see
+  [deploy.md](../../docs/deploy.md)).
+- **`describePoolPressure(runConcurrency, poolMax): string | undefined`** — warns when the worker can
+  execute more runs at once than the Postgres pool can serve.
+- **`resolveMaxPageSize(explicit?, env?): number`** — the same chain for the store page bound:
+  explicit `maxPageSize` → `SKEIN_MAX_PAGE_SIZE` → `DEFAULT_MAX_PAGE_SIZE` (1000). Every driver applies
+  it to list/search, including when the caller asks for no limit.
 - **`loadInMemoryRuntime` / `loadReloadableInMemoryRuntime`** — assemble a `ProtocolDeps` from a
   `langgraph.json` using in-process drivers. The reloadable variant adds `reloadGraphs` /
   `snapshotState` / `hydrateState` (what powers `skein dev`'s hot reload + cross-restart persistence).
 - **`readLanggraphDevState` / `loadSnapshotIntoStore` / `describeSnapshot`** — read an existing
   `.langgraph_api/` directory and reconstruct a `DevStateSnapshot`, so adopting skein carries local
   state over losslessly.
+
+  Imported from **`@skein-js/server-kit/dev`**, not the package root:
+
+  ```ts
+  import { readLanggraphDevState } from "@skein-js/server-kit/dev";
+  ```
+
+  They carry `superjson` and `node:fs/promises`, and only `skein dev` / `skein import` call them, so
+  keeping them on the root barrel put a filesystem snapshot deserializer into every adapter's module
+  graph. There is deliberately no root re-export — a re-export is still a static import. The
+  `DevStateCounts` _type_ remains exported from the root, since `export type` is erased. See
+  [docs/bundling.md](../../docs/bundling.md).
+
 - **CORS** — `corsFromHttpConfig` / `toCorsOptions` map a `langgraph.json` `http.cors` block to
   `cors`-style options; `allowedOrigin` / `corsResponseHeaders` / `applyNodeCors` / `sendNodePreflight`
   derive CORS headers for adapters without a CORS middleware of their own.

package/dist/chunk-JUBBCC7R.js

@@ -0,0 +1,56 @@
+// src/dev-persistence.ts
+var toBase64 = (bytes) => Buffer.from(bytes).toString("base64");
+var fromBase64 = (text) => new Uint8Array(Buffer.from(text, "base64"));
+var mapValues = (record, fn) => Object.fromEntries(Object.entries(record).map(([key, value]) => [key, fn(value)]));
+function snapshotCheckpointer(saver) {
+  return {
+    storage: mapValues(
+      saver.storage,
+      (namespaces) => mapValues(
+        namespaces,
+        (checkpoints) => mapValues(checkpoints, ([checkpoint, metadata, parentId]) => [
+          toBase64(checkpoint),
+          toBase64(metadata),
+          parentId
+        ])
+      )
+    ),
+    writes: mapValues(
+      saver.writes,
+      (taskWrites) => mapValues(taskWrites, ([taskId, channel, blob]) => [
+        taskId,
+        channel,
+        toBase64(blob)
+      ])
+    )
+  };
+}
+function hydrateCheckpointer(saver, snapshot) {
+  saver.storage = mapValues(
+    snapshot.storage,
+    (namespaces) => mapValues(
+      namespaces,
+      (checkpoints) => mapValues(
+        checkpoints,
+        ([checkpoint, metadata, parentId]) => [
+          fromBase64(checkpoint),
+          fromBase64(metadata),
+          parentId
+        ]
+      )
+    )
+  );
+  saver.writes = mapValues(
+    snapshot.writes,
+    (taskWrites) => mapValues(taskWrites, ([taskId, channel, blob]) => [
+      taskId,
+      channel,
+      fromBase64(blob)
+    ])
+  );
+}
+
+export {
+  snapshotCheckpointer,
+  hydrateCheckpointer
+};

package/dist/chunk-QOHYARHD.js

@@ -0,0 +1,237 @@
+import {
+  hydrateCheckpointer,
+  snapshotCheckpointer
+} from "./chunk-JUBBCC7R.js";
+
+// src/in-memory-runtime.ts
+import { MemorySaver as MemorySaver2 } from "@langchain/langgraph";
+import {
+  loadAuthEngine,
+  loadConfig
+} from "@skein-js/config";
+import { MemoryRunEventBus as MemoryRunEventBus2, MemoryRunQueue as MemoryRunQueue2, MemorySkeinStore as MemorySkeinStore2 } from "@skein-js/storage-memory";
+
+// src/cors-config.ts
+import {
+  filterSkeinRoutes,
+  skeinRoutes
+} from "@skein-js/agent-protocol";
+var ALWAYS_EXPOSED_HEADERS = ["content-location", "x-pagination-total"];
+function toCorsOptions(config) {
+  const options = {};
+  const allowAll = config.allow_origins?.includes("*") ?? false;
+  if (config.allow_origin_regex !== void 0) {
+    const pattern = new RegExp(`^(?:${config.allow_origin_regex})$`);
+    const listed = allowAll ? void 0 : new Set(config.allow_origins);
+    options.origin = (origin, callback) => callback(
+      null,
+      origin !== void 0 && (allowAll || pattern.test(origin) || (listed?.has(origin) ?? false))
+    );
+  } else if (config.allow_origins !== void 0) {
+    options.origin = allowAll ? "*" : config.allow_origins;
+  }
+  if (config.allow_methods !== void 0) options.methods = config.allow_methods;
+  if (config.allow_headers !== void 0) options.allowedHeaders = config.allow_headers;
+  if (config.allow_credentials !== void 0) options.credentials = config.allow_credentials;
+  if (config.max_age !== void 0) options.maxAge = config.max_age;
+  const exposed = /* @__PURE__ */ new Set([...ALWAYS_EXPOSED_HEADERS, ...config.expose_headers ?? []]);
+  options.exposedHeaders = [...exposed];
+  return options;
+}
+function corsFromHttpConfig(http) {
+  if (typeof http !== "object" || http === null) return void 0;
+  const cors = http.cors;
+  if (typeof cors !== "object" || cors === null) return void 0;
+  return toCorsOptions(cors);
+}
+var DISABLE_FLAGS = {
+  disable_assistants: "assistants",
+  disable_threads: "threads",
+  disable_runs: "runs",
+  disable_crons: "crons",
+  disable_store: "store",
+  disable_meta: "meta"
+};
+function disabledRoutesFromHttpConfig(http) {
+  if (typeof http !== "object" || http === null) return {};
+  const flags = http;
+  const disabled = {};
+  for (const [flag, group] of Object.entries(DISABLE_FLAGS)) {
+    if (flags[flag] === true) disabled[group] = true;
+  }
+  return disabled;
+}
+function routesFromHttpConfig(http) {
+  return filterSkeinRoutes(skeinRoutes, disabledRoutesFromHttpConfig(http));
+}
+
+// src/in-memory-deps.ts
+import { MemorySaver } from "@langchain/langgraph";
+import { MemoryRunEventBus, MemoryRunQueue, MemorySkeinStore } from "@skein-js/storage-memory";
+
+// src/max-page-size.ts
+import { DEFAULT_MAX_PAGE_SIZE } from "@skein-js/core";
+
+// src/env-numbers.ts
+import { SkeinConfigError } from "@skein-js/config/errors";
+function requirePositiveInteger(source, raw) {
+  const parsed = Number(raw);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new SkeinConfigError(`${source} must be a positive integer (got "${String(raw)}").`);
+  }
+  return parsed;
+}
+function positiveIntegerFromEnv(names, env) {
+  for (const name of names) {
+    const raw = env[name];
+    if (raw === void 0 || raw.trim() === "") continue;
+    return requirePositiveInteger(name, raw);
+  }
+  return void 0;
+}
+
+// src/max-page-size.ts
+var MAX_PAGE_SIZE_ENV_VARS = ["SKEIN_MAX_PAGE_SIZE"];
+function resolveMaxPageSize(explicit, env = process.env) {
+  const fromEnv = positiveIntegerFromEnv(MAX_PAGE_SIZE_ENV_VARS, env);
+  if (explicit === void 0) return fromEnv ?? DEFAULT_MAX_PAGE_SIZE;
+  return requirePositiveInteger("store.maxPageSize", explicit);
+}
+
+// src/memory-bus-limits.ts
+import {
+  DEFAULT_MEMORY_BUS_MAX_FRAMES_PER_RUN,
+  DEFAULT_MEMORY_BUS_MAX_RETAINED_RUNS
+} from "@skein-js/storage-memory";
+var MAX_RETAINED_RUNS_ENV = "SKEIN_MEMORY_BUS_MAX_RETAINED_RUNS";
+var MAX_FRAMES_PER_RUN_ENV = "SKEIN_MEMORY_BUS_MAX_FRAMES_PER_RUN";
+function resolveMemoryBusLimits(explicit = {}, env = process.env) {
+  const retainedFromEnv = positiveIntegerFromEnv([MAX_RETAINED_RUNS_ENV], env);
+  const framesFromEnv = positiveIntegerFromEnv([MAX_FRAMES_PER_RUN_ENV], env);
+  return {
+    maxRetainedRuns: explicit.maxRetainedRuns === void 0 ? retainedFromEnv ?? DEFAULT_MEMORY_BUS_MAX_RETAINED_RUNS : requirePositiveInteger("maxRetainedRuns", explicit.maxRetainedRuns),
+    maxFramesPerRun: explicit.maxFramesPerRun === void 0 ? framesFromEnv ?? DEFAULT_MEMORY_BUS_MAX_FRAMES_PER_RUN : requirePositiveInteger("maxFramesPerRun", explicit.maxFramesPerRun)
+  };
+}
+
+// src/in-memory-deps.ts
+function isGraphResolver(graphs) {
+  const candidate = graphs;
+  return Array.isArray(candidate.ids) && typeof candidate.load === "function";
+}
+function normalizeEmbeddableGraphs(graphs) {
+  return isGraphResolver(graphs) ? graphs : graphMapToResolver(graphs);
+}
+function graphMapToResolver(graphs) {
+  const ids = Object.keys(graphs);
+  return {
+    ids,
+    load: async (graphId) => {
+      const graph = graphs[graphId];
+      if (graph == null) {
+        const known = ids.join(", ") || "none";
+        throw new Error(
+          ids.includes(graphId) ? `Graph "${graphId}" resolved to ${String(graph)} \u2014 check its export/factory (known: ${known}).` : `Unknown graph "${graphId}" (known: ${known}).`
+        );
+      }
+      return graph;
+    },
+    schemas: async (graphId) => ({ [graphId]: { graph_id: graphId } })
+  };
+}
+function embedInMemoryGraphs(graphs, overrides = {}) {
+  return {
+    // `maxPageSize` resolved for the same reason as the bus limits below: an embedded host's
+    // `SKEIN_MAX_PAGE_SIZE` has to reach the driver that applies it.
+    store: new MemorySkeinStore({ maxPageSize: resolveMaxPageSize() }),
+    graphs: normalizeEmbeddableGraphs(graphs),
+    queue: new MemoryRunQueue(),
+    // Resolved rather than defaulted, so `SKEIN_MEMORY_BUS_*` reaches an embedded host too — this is
+    // the driver set a long-lived single-process deployment actually runs on.
+    bus: new MemoryRunEventBus(resolveMemoryBusLimits()),
+    checkpointer: new MemorySaver(),
+    ...overrides
+  };
+}
+var createInMemoryDeps = embedInMemoryGraphs;
+
+// src/in-memory-runtime.ts
+function toGraphResolver(graphs) {
+  return {
+    ids: graphs.ids,
+    load: (graphId) => graphs.load(graphId),
+    schemas: async (graphId) => await graphs.schemas(graphId)
+  };
+}
+async function loadInMemoryRuntime(configPath, importModule, staticSchemas) {
+  const { graphs, config, configDir } = await loadConfig({
+    configPath,
+    importModule,
+    staticSchemas
+  });
+  const deps = embedInMemoryGraphs(toGraphResolver(graphs));
+  deps.auth = await loadAuthEngine(config.auth, { configDir, importModule });
+  return {
+    deps,
+    cors: corsFromHttpConfig(config.http),
+    routes: routesFromHttpConfig(config.http)
+  };
+}
+async function loadReloadableInMemoryRuntime(configPath, importModule, staticSchemas, extraDeps) {
+  const first = await loadConfig({ configPath, importModule, staticSchemas });
+  let current = first.graphs;
+  const graphs = {
+    ids: first.graphs.ids,
+    load: (graphId) => current.load(graphId),
+    schemas: async (graphId) => await current.schemas(graphId)
+  };
+  const store = new MemorySkeinStore2({ maxPageSize: resolveMaxPageSize() });
+  const checkpointer = new MemorySaver2();
+  const deps = {
+    store,
+    graphs,
+    queue: new MemoryRunQueue2(),
+    // This is the path `skein start` and `skein up` take by default, so it is the longest-lived
+    // memory bus skein runs — the bounds have to be resolved here too, not just on the embed paths.
+    bus: new MemoryRunEventBus2(resolveMemoryBusLimits()),
+    checkpointer,
+    auth: await loadAuthEngine(first.config.auth, { configDir: first.configDir, importModule }),
+    ...extraDeps
+  };
+  return {
+    deps,
+    cors: corsFromHttpConfig(first.config.http),
+    routes: routesFromHttpConfig(first.config.http),
+    config: first.config,
+    configDir: first.configDir,
+    reloadGraphs: async () => {
+      current = (await loadConfig({ configPath, importModule, staticSchemas })).graphs;
+    },
+    snapshotState: () => ({
+      version: 1,
+      store: store.snapshot(),
+      checkpoints: snapshotCheckpointer(checkpointer)
+    }),
+    hydrateState: (snapshot) => {
+      store.hydrate(snapshot.store);
+      hydrateCheckpointer(checkpointer, snapshot.checkpoints);
+    }
+  };
+}
+
+export {
+  requirePositiveInteger,
+  positiveIntegerFromEnv,
+  toCorsOptions,
+  corsFromHttpConfig,
+  disabledRoutesFromHttpConfig,
+  routesFromHttpConfig,
+  resolveMaxPageSize,
+  resolveMemoryBusLimits,
+  normalizeEmbeddableGraphs,
+  graphMapToResolver,
+  embedInMemoryGraphs,
+  createInMemoryDeps,
+  loadInMemoryRuntime,
+  loadReloadableInMemoryRuntime
+};

package/dist/dev-BfYYRfEB.d.ts

@@ -0,0 +1,46 @@
+import { BaseCheckpointSaver } from '@langchain/langgraph';
+import { SkeinStore } from '@skein-js/core';
+import { MemoryStoreSnapshot } from '@skein-js/storage-memory';
+
+/** The checkpoint tuple `[checkpoint, metadata, parentId?]` with the blobs base64-encoded. */
+type SerializedCheckpointTuple = [string, string, string | undefined];
+/** `MemorySaver.storage` (thread → namespace → checkpointId → tuple) with blobs base64-encoded. */
+type SerializedCheckpointStorage = Record<string, Record<string, Record<string, SerializedCheckpointTuple>>>;
+/** `MemorySaver.writes` (key → taskId+idx → `[taskId, channel, blob]`) with the blob base64-encoded. */
+type SerializedCheckpointWrites = Record<string, Record<string, [string, string, string]>>;
+interface CheckpointerSnapshot {
+    storage: SerializedCheckpointStorage;
+    writes: SerializedCheckpointWrites;
+}
+/** A JSON-serializable snapshot of the whole in-memory dev runtime. */
+interface DevStateSnapshot {
+    version: 1;
+    store: MemoryStoreSnapshot;
+    checkpoints: CheckpointerSnapshot;
+}
+
+/**
+ * Read a LangGraph `.langgraph_api/` directory and reconstruct skein's `DevStateSnapshot`.
+ * Returns `null` when the directory holds none of the expected files (nothing to import).
+ */
+declare function readLanggraphDevState(langgraphApiDir: string): Promise<DevStateSnapshot | null>;
+/** Row/checkpoint counts in a snapshot, for CLI + log summaries. */
+interface DevStateCounts {
+    assistants: number;
+    threads: number;
+    runs: number;
+    items: number;
+    /** Threads that carry graph checkpoint history. */
+    checkpointedThreads: number;
+}
+declare function describeSnapshot(snapshot: DevStateSnapshot): DevStateCounts;
+/**
+ * Load a `DevStateSnapshot` into a live store + checkpointer — the sink for importing into a real
+ * skein deployment (e.g. Postgres). Resource rows go through the driver's `restore` (ids +
+ * timestamps preserved, `ON CONFLICT DO NOTHING` so re-runs are safe); checkpoints — graph state +
+ * full history — are copied via the public checkpointer API. Throws if the store can't bulk-restore
+ * (both first-party drivers can); a custom driver must implement `restore` to be an import target.
+ */
+declare function loadSnapshotIntoStore(snapshot: DevStateSnapshot, store: SkeinStore, checkpointer: BaseCheckpointSaver): Promise<void>;
+
+export { type DevStateSnapshot as D, type DevStateCounts as a, describeSnapshot as d, loadSnapshotIntoStore as l, readLanggraphDevState as r };

package/dist/dev.d.ts

@@ -0,0 +1,4 @@
+export { a as DevStateCounts, d as describeSnapshot, l as loadSnapshotIntoStore, r as readLanggraphDevState } from './dev-BfYYRfEB.js';
+import '@langchain/langgraph';
+import '@skein-js/core';
+import '@skein-js/storage-memory';