@skein-js/server-kit 0.11.2 → 0.12.0

package/dist/index.js

@@ -1,225 +1,139 @@
-// src/resolve-runtime.ts
 import {
-  createProtocolRuntime
-} from "@skein-js/agent-protocol";
+  corsFromHttpConfig,
+  createInMemoryDeps,
+  disabledRoutesFromHttpConfig,
+  embedInMemoryGraphs,
+  graphMapToResolver,
+  loadInMemoryRuntime,
+  loadReloadableInMemoryRuntime,
+  normalizeEmbeddableGraphs,
+  positiveIntegerFromEnv,
+  requirePositiveInteger,
+  resolveMaxPageSize,
+  resolveMemoryBusLimits,
+  routesFromHttpConfig,
+  toCorsOptions
+} from "./chunk-QOHYARHD.js";
+import "./chunk-JUBBCC7R.js";
 
-// src/in-memory-runtime.ts
-import { MemorySaver as MemorySaver2 } from "@langchain/langgraph";
+// src/resolve-runtime.ts
 import {
-  loadAuthEngine,
-  loadConfig
-} from "@skein-js/config";
-import { MemoryRunEventBus as MemoryRunEventBus2, MemoryRunQueue as MemoryRunQueue2, MemorySkeinStore as MemorySkeinStore2 } from "@skein-js/storage-memory";
+  createProtocolRuntime,
+  skeinRoutes
+} from "@skein-js/agent-protocol";
 
-// src/cors-config.ts
-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);
+// src/cron-tick.ts
+import { DEFAULT_CRON_TICK_MS } from "@skein-js/agent-protocol";
+var CRON_TICK_ENV_VARS = ["SKEIN_CRON_TICK_MS"];
+function resolveCronTickMs(explicit, env = process.env) {
+  const fromEnv = positiveIntegerFromEnv(CRON_TICK_ENV_VARS, env);
+  if (explicit === void 0) return fromEnv ?? DEFAULT_CRON_TICK_MS;
+  return requirePositiveInteger("scheduler.tickMs", explicit);
 }
 
-// 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)
-    ])
-  );
-}
-
-// src/in-memory-deps.ts
-import { MemorySaver } from "@langchain/langgraph";
-import { MemoryRunEventBus, MemoryRunQueue, MemorySkeinStore } from "@skein-js/storage-memory";
-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 {
-    store: new MemorySkeinStore(),
-    graphs: normalizeEmbeddableGraphs(graphs),
-    queue: new MemoryRunQueue(),
-    bus: new MemoryRunEventBus(),
-    checkpointer: new MemorySaver(),
-    ...overrides
+// src/heap-pressure.ts
+import { getHeapStatistics } from "v8";
+import { SkeinConfigError } from "@skein-js/config/errors";
+var DEFAULT_HEAP_WARN_PERCENT = 85;
+var HEAP_REARM_MARGIN_PERCENT = 15;
+var HEAP_REARM_PERCENT = DEFAULT_HEAP_WARN_PERCENT - HEAP_REARM_MARGIN_PERCENT;
+var DEFAULT_HEAP_SAMPLE_MS = 3e4;
+function megabytes(bytes) {
+  return `${Math.round(bytes / 1048576)}MB`;
+}
+function startHeapPressureMonitor(options = {}) {
+  const {
+    logger,
+    warnPercent = DEFAULT_HEAP_WARN_PERCENT,
+    sampleMs = DEFAULT_HEAP_SAMPLE_MS,
+    context,
+    heapStatistics = getHeapStatistics,
+    rss = () => process.memoryUsage().rss,
+    setInterval: schedule = (callback, ms) => setInterval(callback, ms),
+    clearInterval: unschedule = (handle2) => clearInterval(handle2)
+  } = options;
+  if (!logger || warnPercent <= 0 || sampleMs <= 0) return { stop: () => {
+  } };
+  const rearmPercent = Math.max(0, warnPercent - HEAP_REARM_MARGIN_PERCENT);
+  let warned = false;
+  const sample = () => {
+    const { heap_size_limit: limit, used_heap_size: used } = heapStatistics();
+    if (limit <= 0) return;
+    const percent = used / limit * 100;
+    if (warned) {
+      if (percent < rearmPercent) warned = false;
+      return;
+    }
+    if (percent < warnPercent) return;
+    warned = true;
+    const extra = context?.() ?? {};
+    const details = [
+      `heap ${megabytes(used)}/${megabytes(limit)} (${Math.round(percent)}%)`,
+      `rss ${megabytes(rss())}`,
+      extra.inFlightRuns !== void 0 ? `runs in flight ${extra.inFlightRuns}` : void 0,
+      extra.bufferedFrames !== void 0 ? `buffered frames ${extra.bufferedFrames}` : void 0
+    ].filter(Boolean);
+    logger.warn?.(
+      `skein: heap pressure \u2014 ${details.join(", ")}. Many runs in flight suggests lowering SKEIN_RUN_CONCURRENCY; a large buffered-frame count suggests a slow SSE consumer (see SKEIN_MEMORY_BUS_MAX_FRAMES_PER_RUN); neither suggests a leak. Next warning only after usage drops below ${rearmPercent}%.`
+    );
   };
-}
-var createInMemoryDeps = embedInMemoryGraphs;
-
-// src/in-memory-runtime.ts
-function toGraphResolver(graphs) {
+  const handle = schedule(sample, sampleMs);
+  handle.unref?.();
+  let stopped = false;
   return {
-    ids: graphs.ids,
-    load: (graphId) => graphs.load(graphId),
-    schemas: async (graphId) => await graphs.schemas(graphId)
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      unschedule(handle);
+    }
   };
 }
-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 });
+function resolveHeapPressureOptions(explicit = {}, env = process.env) {
+  const warnFromEnv = percentFromEnv(env["SKEIN_HEAP_WARN_PERCENT"]);
+  const sampleFromEnv = positiveIntegerFromEnv(["SKEIN_HEAP_SAMPLE_MS"], env);
   return {
-    deps,
-    cors: corsFromHttpConfig(config.http)
+    warnPercent: explicit.warnPercent ?? warnFromEnv ?? DEFAULT_HEAP_WARN_PERCENT,
+    sampleMs: explicit.sampleMs ?? sampleFromEnv ?? DEFAULT_HEAP_SAMPLE_MS
   };
 }
-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();
-  const checkpointer = new MemorySaver2();
-  const deps = {
-    store,
-    graphs,
-    queue: new MemoryRunQueue2(),
-    bus: new MemoryRunEventBus2(),
-    checkpointer,
-    auth: await loadAuthEngine(first.config.auth, { configDir: first.configDir, importModule }),
-    ...extraDeps
-  };
-  return {
-    deps,
-    cors: corsFromHttpConfig(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);
-    }
-  };
+function percentFromEnv(raw) {
+  if (raw === void 0 || raw.trim() === "") return void 0;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0 || value > 100) {
+    throw new SkeinConfigError(
+      `SKEIN_HEAP_WARN_PERCENT must be an integer between 0 and 100 (got "${raw}").`
+    );
+  }
+  return value;
 }
 
 // src/run-concurrency.ts
 import { DEFAULT_RUN_CONCURRENCY } from "@skein-js/agent-protocol";
-import { SkeinConfigError } from "@skein-js/config";
+var PG_DEFAULT_POOL_MAX = 10;
 var CONCURRENCY_ENV_VARS = ["SKEIN_RUN_CONCURRENCY", "N_JOBS_PER_WORKER"];
-function requirePositiveInteger(source, raw) {
-  const parsed = Number(raw);
-  if (!Number.isInteger(parsed) || parsed <= 0) {
-    throw new SkeinConfigError(`${source} must be a positive integer (got "${String(raw)}").`);
-  }
-  return parsed;
-}
-function runConcurrencyFromEnv(env) {
-  for (const name of CONCURRENCY_ENV_VARS) {
-    const raw = env[name];
-    if (raw === void 0 || raw.trim() === "") continue;
-    return requirePositiveInteger(name, raw);
-  }
-  return void 0;
-}
 function resolveRunConcurrency(explicit, env = process.env) {
-  const fromEnv = runConcurrencyFromEnv(env);
+  const fromEnv = positiveIntegerFromEnv(CONCURRENCY_ENV_VARS, env);
   if (explicit === void 0) return fromEnv ?? DEFAULT_RUN_CONCURRENCY;
   return requirePositiveInteger("worker.maxConcurrency", explicit);
 }
+function describePoolPressure(runConcurrency, poolMax) {
+  const effectivePoolMax = poolMax ?? PG_DEFAULT_POOL_MAX;
+  if (runConcurrency <= effectivePoolMax) return void 0;
+  const source = poolMax === void 0 ? `pg's default of ${PG_DEFAULT_POOL_MAX}` : `PG_POOL_MAX`;
+  return `Run concurrency (${runConcurrency}) is higher than the Postgres pool allows (${effectivePoolMax}, from ${source}). Runs will queue waiting for a connection rather than executing, which looks like flat throughput rather than like a pool limit. Raise PG_POOL_MAX to at least ${runConcurrency}, or lower SKEIN_RUN_CONCURRENCY. Note skein opens two pools per instance (store + checkpointer), so budget ${runConcurrency * 2} connections against your database's own cap.`;
+}
+
+// src/run-timeout.ts
+var RUN_TIMEOUT_ENV_VARS = ["SKEIN_RUN_TIMEOUT_MS"];
+function resolveRunTimeoutMs(explicit, env = process.env) {
+  const fromEnv = positiveIntegerFromEnv(RUN_TIMEOUT_ENV_VARS, env);
+  if (explicit === void 0) return fromEnv;
+  return requirePositiveInteger("runTimeoutMs", explicit);
+}
 
 // src/shutdown-grace.ts
 import { DEFAULT_SHUTDOWN_GRACE_MS } from "@skein-js/agent-protocol";
-import { SkeinConfigError as SkeinConfigError2 } from "@skein-js/config";
+import { SkeinConfigError as SkeinConfigError2 } from "@skein-js/config/errors";
 var SHUTDOWN_GRACE_ENV_VAR = "SKEIN_SHUTDOWN_GRACE_MS";
 function requireNonNegativeInteger(source, raw) {
   const parsed = Number(raw);
@@ -248,18 +162,33 @@ function resolveLogger(option, injected, frameworkLogger) {
   return option ?? frameworkLogger;
 }
 async function resolveRuntimeDeps(options, frameworkLogger) {
-  const loaded = options.deps ? { deps: options.deps, cors: void 0 } : await loadInMemoryRuntime(options.config, options.importModule);
+  const loaded = options.deps ? { deps: options.deps, cors: void 0, routes: skeinRoutes } : await (await import("./in-memory-runtime-32UYJRVJ.js")).loadInMemoryRuntime(options.config, options.importModule);
   const logger = resolveLogger(options.logger, loaded.deps.logger, frameworkLogger);
   if (logger && !loaded.deps.logger) loaded.deps.logger = logger;
-  return { deps: loaded.deps, cors: loaded.cors, logger };
+  return { deps: loaded.deps, cors: loaded.cors, routes: loaded.routes, logger };
 }
 async function resolveProtocolRuntime(options, frameworkLogger) {
-  const { deps, cors: corsFromConfig, logger } = await resolveRuntimeDeps(options, frameworkLogger);
+  const {
+    deps,
+    cors: corsFromConfig,
+    routes,
+    logger
+  } = await resolveRuntimeDeps(options, frameworkLogger);
+  const heapPressureOptions = resolveHeapPressureOptions();
+  const runTimeoutMs = resolveRunTimeoutMs(deps.runTimeoutMs);
+  if (runTimeoutMs !== void 0) deps.runTimeoutMs = runTimeoutMs;
   const runtime = createProtocolRuntime(deps, {
     worker: {
       ...options.worker,
       maxConcurrency: resolveRunConcurrency(options.worker?.maxConcurrency),
       shutdownGraceMs: resolveShutdownGraceMs(options.worker?.shutdownGraceMs)
+    },
+    scheduler: {
+      ...options.scheduler,
+      tickMs: resolveCronTickMs(options.scheduler?.tickMs),
+      // `http.disable_crons` takes the whole resource away, so the scheduler goes with it: leaving
+      // it ticking would keep firing schedules nobody can see, list, or cancel any more.
+      enabled: options.scheduler?.enabled ?? routes.some((route) => route.group === "crons")
     }
   });
   await runtime.service.assistants.registerGraphAssistants();
@@ -273,7 +202,31 @@ async function resolveProtocolRuntime(options, frameworkLogger) {
     );
   }
   runtime.worker.start();
-  return { runtime, cors: corsFromConfig, logger };
+  const heapMonitor = startHeapPressureMonitor({
+    ...logger ? { logger } : {},
+    ...heapPressureOptions,
+    // Read at warn time only. `bufferedFrameCount` is a diagnostic the in-memory bus exposes and the
+    // Redis one does not, so it is probed rather than required — on Redis the frames are not in this
+    // process's heap anyway, which is itself part of the answer.
+    context: () => {
+      const bufferedFrames = deps.bus.bufferedFrameCount;
+      return {
+        inFlightRuns: runtime.worker.inFlightRunCount,
+        ...typeof bufferedFrames === "number" ? { bufferedFrames } : {}
+      };
+    }
+  });
+  const worker = {
+    get inFlightRunCount() {
+      return runtime.worker.inFlightRunCount;
+    },
+    start: () => runtime.worker.start(),
+    stop: async () => {
+      heapMonitor.stop();
+      await runtime.worker.stop();
+    }
+  };
+  return { runtime: { ...runtime, worker }, cors: corsFromConfig, routes, logger };
 }
 
 // src/log-meta.ts
@@ -389,302 +342,65 @@ ${rendered}` : ""}`);
   };
 }
 
-// src/index.ts
-import { DEFAULT_RUN_CONCURRENCY as DEFAULT_RUN_CONCURRENCY2 } from "@skein-js/agent-protocol";
-import { DEFAULT_SHUTDOWN_GRACE_MS as DEFAULT_SHUTDOWN_GRACE_MS2 } from "@skein-js/agent-protocol";
-
-// src/langgraph-import.ts
-import { readFile } from "fs/promises";
-import path from "path";
-import {
-  MemorySaver as MemorySaver3
-} from "@langchain/langgraph";
-import {
-  isTerminalRunStatus
-} from "@skein-js/core";
-import { SuperJSON } from "superjson";
-import { z } from "zod";
-var OPS_FILE = ".langgraphjs_ops.json";
-var STORE_FILE = ".langgraphjs_api.store.json";
-var CHECKPOINTER_FILE = ".langgraphjs_api.checkpointer.json";
-var langgraphSuperjson = new SuperJSON();
-langgraphSuperjson.registerCustom(
-  {
-    isApplicable: (value) => value instanceof Uint8Array,
-    serialize: (value) => Buffer.from(value).toString("base64"),
-    deserialize: (value) => new Uint8Array(Buffer.from(value, "base64"))
-  },
-  "Uint8Array"
-);
-var timestamp = z.union([z.date(), z.string()]).optional();
-var jsonObject = z.record(z.unknown());
-var langgraphAssistantSchema = z.object({
-  assistant_id: z.string(),
-  graph_id: z.string(),
-  name: z.string().optional(),
-  description: z.string().nullish(),
-  config: jsonObject.optional(),
-  context: z.unknown().optional(),
-  metadata: jsonObject.optional(),
-  version: z.number().optional(),
-  created_at: timestamp,
-  updated_at: timestamp
-}).passthrough();
-var langgraphAssistantVersionSchema = z.object({
-  assistant_id: z.string(),
-  version: z.number(),
-  graph_id: z.string(),
-  name: z.string().optional(),
-  description: z.string().nullish(),
-  config: jsonObject.optional(),
-  context: z.unknown().optional(),
-  metadata: jsonObject.optional(),
-  created_at: timestamp
-}).passthrough();
-var langgraphThreadSchema = z.object({
-  thread_id: z.string(),
-  status: z.string().optional(),
-  metadata: jsonObject.optional(),
-  values: jsonObject.optional(),
-  interrupts: jsonObject.optional(),
-  created_at: timestamp,
-  updated_at: timestamp
-}).passthrough();
-var langgraphRunSchema = z.object({
-  run_id: z.string(),
-  thread_id: z.string(),
-  assistant_id: z.string(),
-  status: z.string().optional(),
-  metadata: jsonObject.optional(),
-  multitask_strategy: z.string().nullish(),
-  kwargs: jsonObject.optional(),
-  created_at: timestamp,
-  updated_at: timestamp
-}).passthrough();
-var langgraphOpsSchema = z.object({
-  assistants: z.record(langgraphAssistantSchema).optional(),
-  assistant_versions: z.array(langgraphAssistantVersionSchema).optional(),
-  threads: z.record(langgraphThreadSchema).optional(),
-  runs: z.record(langgraphRunSchema).optional()
-}).passthrough();
-var langgraphStoreItemSchema = z.object({
-  namespace: z.array(z.string()),
-  key: z.string(),
-  value: jsonObject,
-  createdAt: timestamp,
-  updatedAt: timestamp
-}).passthrough();
-var langgraphStoreFileSchema = z.object({ data: z.map(z.string(), z.map(z.string(), langgraphStoreItemSchema)).optional() }).passthrough();
-var langgraphCheckpointerSchema = z.object({ storage: jsonObject, writes: jsonObject }).passthrough();
-async function readSuperjsonFile(filepath) {
-  let text;
+// src/heap-headroom.ts
+import { readFileSync } from "fs";
+import { getHeapStatistics as getHeapStatistics2 } from "v8";
+var HEAP_LIMIT_WARN_FRACTION = 0.75;
+var HEAP_LIMIT_SUGGEST_FRACTION = 0.6;
+var MEMORY_LIMIT_FILES = [
+  "/sys/fs/cgroup/memory.max",
+  "/sys/fs/cgroup/memory/memory.limit_in_bytes"
+];
+var readFileIfPresent = (path) => {
   try {
-    text = await readFile(filepath, "utf8");
+    return readFileSync(path, "utf8");
   } catch {
-    return null;
-  }
-  try {
-    return langgraphSuperjson.parse(text) ?? null;
-  } catch (error) {
-    throw new Error(
-      `Could not parse LangGraph state file "${filepath}": ${error instanceof Error ? error.message : String(error)}`
-    );
+    return void 0;
   }
-}
-function validateShape(schema, value, label) {
-  const result = schema.safeParse(value);
-  if (!result.success) {
-    const detail = result.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
-    throw new Error(`Invalid LangGraph ${label}: ${detail}`);
+};
+function readContainerMemoryLimit(readFile = readFileIfPresent) {
+  for (const path of MEMORY_LIMIT_FILES) {
+    const raw = readFile(path)?.trim();
+    if (raw === void 0 || raw === "" || raw === "max") continue;
+    const bytes = Number(raw);
+    if (!Number.isFinite(bytes) || bytes <= 0) continue;
+    if (bytes >= Number.MAX_SAFE_INTEGER) continue;
+    return bytes;
   }
-  return result.data;
-}
-function toIso(value, fallback) {
-  if (value instanceof Date) return value.toISOString();
-  if (typeof value === "string") return value;
-  return fallback;
-}
-function toAssistant(row, now) {
-  return {
-    assistant_id: row.assistant_id,
-    graph_id: row.graph_id,
-    name: row.name ?? row.graph_id,
-    description: row.description ?? void 0,
-    config: row.config ?? {},
-    context: row.context ?? {},
-    metadata: row.metadata ?? {},
-    version: row.version ?? 1,
-    created_at: toIso(row.created_at, now),
-    updated_at: toIso(row.updated_at, now)
-  };
-}
-function toAssistantVersion(row, now) {
-  return {
-    assistant_id: row.assistant_id,
-    version: row.version,
-    graph_id: row.graph_id,
-    name: row.name ?? row.graph_id,
-    description: row.description ?? void 0,
-    config: row.config ?? {},
-    context: row.context ?? {},
-    metadata: row.metadata ?? {},
-    created_at: toIso(row.created_at, now)
-  };
-}
-function toThread(row, now) {
-  const createdAt = toIso(row.created_at, now);
-  const updatedAt = toIso(row.updated_at, createdAt);
-  return {
-    thread_id: row.thread_id,
-    status: row.status ?? "idle",
-    metadata: row.metadata ?? {},
-    values: row.values ?? {},
-    interrupts: row.interrupts ?? {},
-    created_at: createdAt,
-    updated_at: updatedAt,
-    state_updated_at: updatedAt
-  };
-}
-function toRun(row, now) {
-  const createdAt = toIso(row.created_at, now);
-  const status = row.status ?? "success";
-  return {
-    run_id: row.run_id,
-    thread_id: row.thread_id,
-    assistant_id: row.assistant_id,
-    status: isTerminalRunStatus(status) ? status : "error",
-    metadata: row.metadata ?? {},
-    multitask_strategy: row.multitask_strategy ?? null,
-    created_at: createdAt,
-    updated_at: toIso(row.updated_at, createdAt)
-  };
+  return void 0;
 }
-function toRunKwargs(kwargs) {
-  if (!kwargs) return {};
-  const {
-    input,
-    command,
-    config,
-    context,
-    stream_mode,
-    interrupt_before,
-    interrupt_after,
-    webhook
-  } = kwargs;
-  return {
-    input,
-    command,
-    config,
-    context,
-    stream_mode,
-    interrupt_before,
-    interrupt_after,
-    ...typeof webhook === "string" ? { webhook } : {}
-  };
+function megabytes2(bytes) {
+  return `${Math.round(bytes / 1048576)}MB`;
 }
-async function readLanggraphDevState(langgraphApiDir) {
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  const [opsRaw, storeRaw, checkpointerRaw] = await Promise.all([
-    readSuperjsonFile(path.join(langgraphApiDir, OPS_FILE)),
-    readSuperjsonFile(path.join(langgraphApiDir, STORE_FILE)),
-    readSuperjsonFile(path.join(langgraphApiDir, CHECKPOINTER_FILE))
-  ]);
-  if (!opsRaw && !storeRaw && !checkpointerRaw) return null;
-  const ops = opsRaw ? validateShape(langgraphOpsSchema, opsRaw, OPS_FILE) : null;
-  const storeFile = storeRaw ? validateShape(langgraphStoreFileSchema, storeRaw, STORE_FILE) : null;
-  const checkpointerFile = checkpointerRaw ? validateShape(langgraphCheckpointerSchema, checkpointerRaw, CHECKPOINTER_FILE) : null;
-  const runEntries = Object.entries(ops?.runs ?? {});
-  const items = [];
-  if (storeFile?.data) {
-    for (const namespaceItems of storeFile.data.values()) {
-      for (const stored of namespaceItems.values()) {
-        const item = {
-          namespace: stored.namespace,
-          key: stored.key,
-          value: stored.value,
-          createdAt: toIso(stored.createdAt, now),
-          updatedAt: toIso(stored.updatedAt, now)
-        };
-        items.push([JSON.stringify([stored.namespace, stored.key]), item]);
-      }
-    }
-  }
-  const store = {
-    assistants: Object.entries(ops?.assistants ?? {}).map(([id, row]) => [
-      id,
-      toAssistant(row, now)
-    ]),
-    assistantVersions: (ops?.assistant_versions ?? []).map((row) => [
-      JSON.stringify([row.assistant_id, row.version]),
-      toAssistantVersion(row, now)
-    ]),
-    threads: Object.entries(ops?.threads ?? {}).map(([id, row]) => [id, toThread(row, now)]),
-    runs: runEntries.map(([id, row]) => [id, toRun(row, now)]),
-    runKwargs: runEntries.map(([id, row]) => [id, toRunKwargs(row.kwargs)]),
-    items
-  };
-  let checkpoints = { storage: {}, writes: {} };
-  if (checkpointerFile) {
-    const saver = new MemorySaver3();
-    saver.storage = checkpointerFile.storage;
-    saver.writes = checkpointerFile.writes;
-    checkpoints = snapshotCheckpointer(saver);
+function describeHeapHeadroom(heapLimitBytes, containerLimitBytes) {
+  if (containerLimitBytes === void 0 || heapLimitBytes <= containerLimitBytes * HEAP_LIMIT_WARN_FRACTION) {
+    return { heapLimitBytes, containerLimitBytes, warning: void 0 };
   }
-  return { version: 1, store, checkpoints };
-}
-function describeSnapshot(snapshot) {
+  const suggestedMb = Math.floor(containerLimitBytes * HEAP_LIMIT_SUGGEST_FRACTION / 1048576);
   return {
-    assistants: snapshot.store.assistants.length,
-    threads: snapshot.store.threads.length,
-    runs: snapshot.store.runs.length,
-    items: snapshot.store.items.length,
-    checkpointedThreads: Object.keys(snapshot.checkpoints.storage).length
+    heapLimitBytes,
+    containerLimitBytes,
+    warning: `V8's heap limit (${megabytes2(heapLimitBytes)}) is close to or above this container's memory limit (${megabytes2(containerLimitBytes)}). Node's automatic sizing has a floor of about 259MB, so below roughly 345Mi it stops adapting \u2014 V8 may not run a full GC before the kernel OOM-kills the process, which looks like an unexplained restart rather than a memory error. Lower it explicitly with NODE_OPTIONS="--enable-source-maps --max-old-space-size=${suggestedMb}", or give the container more memory. Keep --enable-source-maps: NODE_OPTIONS replaces the image's value rather than adding to it, so setting it without that flag silently loses TypeScript stack traces.`
   };
 }
-function supportsRestore(store) {
-  return typeof store.restore === "function";
-}
-async function copyCheckpoints(snapshot, target) {
-  const source = new MemorySaver3();
-  hydrateCheckpointer(source, snapshot);
-  const tuples = [];
-  for await (const tuple of source.list({})) tuples.push(tuple);
-  tuples.reverse();
-  for (const tuple of tuples) {
-    const configurable = tuple.config.configurable ?? {};
-    const putConfig = {
-      configurable: {
-        thread_id: configurable.thread_id,
-        checkpoint_ns: configurable.checkpoint_ns ?? "",
-        // `put` reads `checkpoint_id` as the PARENT pointer; the child's own id is `checkpoint.id`.
-        checkpoint_id: tuple.parentConfig?.configurable?.checkpoint_id
-      }
-    };
-    const stored = await target.put(
-      putConfig,
-      tuple.checkpoint,
-      tuple.metadata ?? {},
-      tuple.checkpoint.channel_versions ?? {}
-    );
-    const writesByTask = /* @__PURE__ */ new Map();
-    for (const [taskId, channel, value] of tuple.pendingWrites ?? []) {
-      const writes = writesByTask.get(taskId) ?? [];
-      writes.push([channel, value]);
-      writesByTask.set(taskId, writes);
-    }
-    for (const [taskId, writes] of writesByTask) {
-      await target.putWrites(stored, writes, taskId);
-    }
-  }
+function checkHeapHeadroom(options = {}) {
+  const heapLimit = (options.heapStatistics ?? getHeapStatistics2)().heap_size_limit;
+  return describeHeapHeadroom(heapLimit, readContainerMemoryLimit(options.readFile));
 }
-async function loadSnapshotIntoStore(snapshot, store, checkpointer) {
-  if (!supportsRestore(store)) {
-    throw new Error(
-      "Target store does not support bulk import (no restore() method). Use the in-memory or Postgres driver, or implement restore() on your SkeinStore."
-    );
-  }
-  await store.restore(snapshot.store);
-  await copyCheckpoints(snapshot.checkpoints, checkpointer);
+
+// src/index.ts
+import { DEFAULT_RUN_CONCURRENCY as DEFAULT_RUN_CONCURRENCY2 } from "@skein-js/agent-protocol";
+import { DEFAULT_SHUTDOWN_GRACE_MS as DEFAULT_SHUTDOWN_GRACE_MS2 } from "@skein-js/agent-protocol";
+
+// src/route-matcher-cache.ts
+import { createRouteMatcher } from "@skein-js/agent-protocol";
+var matchers = /* @__PURE__ */ new WeakMap();
+function routeMatcherFor(routes) {
+  const existing = matchers.get(routes);
+  if (existing) return existing;
+  const matcher = createRouteMatcher(routes);
+  matchers.set(routes, matcher);
+  return matcher;
 }
 
 // src/cors-runtime.ts
@@ -755,12 +471,15 @@ function sendNodePreflight(reqHeaders, res, cors) {
 }
 
 // src/node-transport.ts
-import { SSE_HEADERS } from "@skein-js/agent-protocol";
+import {
+  SSE_HEADERS,
+  writeWithBackpressure
+} from "@skein-js/agent-protocol";
 import { isSkeinHttpError, serializeWireJson } from "@skein-js/core";
 var ignoreStreamError = () => {
 };
-async function pipeServerSentEvents(status, events, res) {
-  res.writeHead(status, SSE_HEADERS);
+async function pipeServerSentEvents(status, events, res, headers = {}) {
+  res.writeHead(status, { ...SSE_HEADERS, ...headers });
   res.flushHeaders();
   const iterator = events[Symbol.asyncIterator]();
   let clientDisconnected = false;
@@ -774,7 +493,8 @@ async function pipeServerSentEvents(status, events, res) {
     for (; ; ) {
       const next = await iterator.next();
       if (next.done || clientDisconnected) break;
-      res.write(next.value);
+      const drained = writeWithBackpressure(res, next.value);
+      if (drained) await drained;
     }
   } finally {
     res.removeListener("close", releaseOnClientClose);
@@ -784,14 +504,17 @@ async function pipeServerSentEvents(status, events, res) {
 async function sendNodeResponse(response, res) {
   switch (response.kind) {
     case "json":
-      res.writeHead(response.status, { "content-type": "application/json" });
+      res.writeHead(response.status, {
+        "content-type": "application/json",
+        ...response.headers
+      });
       res.end(serializeWireJson(response.body));
       return;
     case "empty":
-      res.writeHead(response.status).end();
+      res.writeHead(response.status, response.headers).end();
       return;
     case "sse":
-      await pipeServerSentEvents(response.status, response.events, res);
+      await pipeServerSentEvents(response.status, response.events, res, response.headers);
       return;
   }
 }
@@ -831,35 +554,139 @@ function stripBasePath(pathname, basePath) {
   if (pathname.startsWith(`${prefix}/`)) return pathname.slice(prefix.length);
   return null;
 }
+
+// src/runtime-capabilities.ts
+function detectRuntimeCapabilities(scope = globalThis) {
+  const monotonic = () => scope.performance?.now() ?? Date.now();
+  const commonClock = { nowEpochMs: Date.now, nowMonotonicMs: monotonic };
+  if (scope.Bun) {
+    const bun = scope.Bun;
+    const process3 = scope.process;
+    if (!process3) throw new Error("Bun runtime does not expose process lifecycle compatibility.");
+    return {
+      name: "bun",
+      version: bun.version,
+      env: {
+        get: (name) => bun.env[name],
+        set: (name, value) => {
+          bun.env[name] = value;
+        }
+      },
+      clock: commonClock,
+      memory: {
+        read: () => {
+          const native = bun.memoryUsage?.();
+          const fallback = process3.memoryUsage();
+          return {
+            rssBytes: native?.rss ?? fallback.rss,
+            heapUsedBytes: native?.heapUsed ?? fallback.heapUsed,
+            nativeHeapBytes: native?.current
+          };
+        }
+      },
+      signals: {
+        on: (signal, listener) => {
+          process3.on(signal, listener);
+          return { dispose: () => process3.off(signal, listener) };
+        }
+      },
+      exit: (code) => process3.exit(code)
+    };
+  }
+  if (scope.Deno) {
+    const deno = scope.Deno;
+    return {
+      name: "deno",
+      version: deno.version.deno,
+      env: deno.env,
+      clock: commonClock,
+      memory: {
+        read: () => {
+          const memory = deno.memoryUsage();
+          return { rssBytes: memory.rss, heapUsedBytes: memory.heapUsed };
+        }
+      },
+      signals: {
+        on: (signal, listener) => {
+          deno.addSignalListener(signal, listener);
+          return { dispose: () => deno.removeSignalListener(signal, listener) };
+        }
+      },
+      exit: (code) => deno.exit(code)
+    };
+  }
+  const process2 = scope.process;
+  if (!process2)
+    throw new Error("Unsupported JavaScript runtime: process, Bun, and Deno are absent.");
+  return {
+    name: "node",
+    version: process2.version.replace(/^v/, ""),
+    env: {
+      get: (name) => process2.env[name],
+      set: (name, value) => {
+        process2.env[name] = value;
+      }
+    },
+    clock: commonClock,
+    memory: {
+      read: () => {
+        const memory = process2.memoryUsage();
+        return { rssBytes: memory.rss, heapUsedBytes: memory.heapUsed };
+      }
+    },
+    signals: {
+      on: (signal, listener) => {
+        process2.on(signal, listener);
+        return { dispose: () => process2.off(signal, listener) };
+      }
+    },
+    exit: (code) => process2.exit(code)
+  };
+}
 export {
+  DEFAULT_HEAP_SAMPLE_MS,
+  DEFAULT_HEAP_WARN_PERCENT,
   DEFAULT_RUN_CONCURRENCY2 as DEFAULT_RUN_CONCURRENCY,
   DEFAULT_SHUTDOWN_GRACE_MS2 as DEFAULT_SHUTDOWN_GRACE_MS,
+  HEAP_REARM_MARGIN_PERCENT,
+  HEAP_REARM_PERCENT,
   allowedOrigin,
   applyNodeCors,
+  checkHeapHeadroom,
   corsFromHttpConfig,
   corsPreflightHeaders,
   corsResponseHeaders,
   createConsoleLogger,
   createInMemoryDeps,
   describeError,
-  describeSnapshot,
+  describeHeapHeadroom,
+  describePoolPressure,
+  detectRuntimeCapabilities,
+  disabledRoutesFromHttpConfig,
   embedInMemoryGraphs,
   formatLogMeta,
   graphMapToResolver,
   joinList,
   loadInMemoryRuntime,
   loadReloadableInMemoryRuntime,
-  loadSnapshotIntoStore,
   normalizeEmbeddableGraphs,
-  readLanggraphDevState,
+  readContainerMemoryLimit,
+  resolveCronTickMs,
+  resolveHeapPressureOptions,
+  resolveMaxPageSize,
+  resolveMemoryBusLimits,
   resolveProtocolRuntime,
   resolveRunConcurrency,
+  resolveRunTimeoutMs,
   resolveRuntimeDeps,
   resolveShutdownGraceMs,
+  routeMatcherFor,
+  routesFromHttpConfig,
   runFailureIdentity,
   sendNodeError,
   sendNodePreflight,
   sendNodeResponse,
+  startHeapPressureMonitor,
   stripBasePath,
   toCorsOptions
 };