@skein-js/server-kit 0.13.0 → 0.14.0

package/README.md

@@ -1,5 +1,7 @@
 # @skein-js/server-kit
 
+[![npm](https://img.shields.io/npm/v/%40skein-js%2Fserver-kit?logo=npm&color=cb3837)](https://www.npmjs.com/package/@skein-js/server-kit) [![downloads](https://img.shields.io/npm/dm/%40skein-js%2Fserver-kit?color=blue)](https://www.npmjs.com/package/@skein-js/server-kit) [![license](https://img.shields.io/npm/l/%40skein-js%2Fserver-kit?color=green)](../../LICENSE)
+
 > Shared, framework-agnostic building blocks for skein-js HTTP adapters.
 
 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.
@@ -107,9 +109,16 @@ Pass `overrides` to swap in production drivers or an auth engine while keeping t
 - **`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.
+- **`resolveStoreTtl(raw?)` / `resolveThreadTtl(raw?)`** — map the `langgraph.json` `store.ttl` and
+  `checkpointer.ttl` blocks (snake_case, minutes) onto the drivers' camelCase `StoreTtlConfig` /
+  `ThreadTtlConfig`; `undefined` when unset, so nothing expires unless asked. Plus the raw input types
+  `RawStoreTtl` / `RawThreadTtl`. They live here rather than in `@skein-js/runtime` because **both**
+  assembly paths need them and neither owns the other — resolving a block in only one is how a TTL
+  came to work under `skein start` and silently do nothing under `skein dev`.
 - **`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).
+  `langgraph.json` using in-process drivers, reading both TTL blocks itself. 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.

package/dist/{chunk-QOHYARHD.js → chunk-XDS3YWFL.js}

@@ -16,7 +16,8 @@ import {
   filterSkeinRoutes,
   skeinRoutes
 } from "@skein-js/agent-protocol";
-var ALWAYS_EXPOSED_HEADERS = ["content-location", "x-pagination-total"];
+var ALWAYS_EXPOSED_HEADERS = ["content-location", "x-pagination-total", "idempotent-replay"];
+var ALWAYS_ALLOWED_HEADERS = ["idempotency-key"];
 function toCorsOptions(config) {
   const options = {};
   const allowAll = config.allow_origins?.includes("*") ?? false;
@@ -31,7 +32,13 @@ function toCorsOptions(config) {
     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_headers !== void 0) {
+    const configured = new Set(config.allow_headers.map((header) => header.toLowerCase()));
+    options.allowedHeaders = config.allow_headers.length === 0 ? [] : [
+      ...config.allow_headers,
+      ...ALWAYS_ALLOWED_HEADERS.filter((header) => !configured.has(header))
+    ];
+  }
   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 ?? []]);
@@ -64,6 +71,31 @@ function disabledRoutesFromHttpConfig(http) {
 function routesFromHttpConfig(http) {
   return filterSkeinRoutes(skeinRoutes, disabledRoutesFromHttpConfig(http));
 }
+function consoleMountFromHttpConfig(http) {
+  if (typeof http !== "object" || http === null) return void 0;
+  const value = http["console"];
+  if (value === true) return DEFAULT_CONSOLE_MOUNT;
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  if (/^(false|0|off|no)$/i.test(trimmed)) return void 0;
+  if (/^(true|1|on|yes)$/i.test(trimmed)) return DEFAULT_CONSOLE_MOUNT;
+  if (trimmed === "" || trimmed === "/") return void 0;
+  const withLeadingSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return withLeadingSlash.replace(/\/+$/, "");
+}
+var DEFAULT_CONSOLE_MOUNT = "/console";
+
+// src/idempotency-config.ts
+function resolveIdempotency(raw) {
+  if (!raw) return void 0;
+  const config = {};
+  if (typeof raw.retention_hours === "number") config.retentionHours = raw.retention_hours;
+  if (typeof raw.in_flight_minutes === "number") config.inFlightMinutes = raw.in_flight_minutes;
+  if (typeof raw.sweep_interval_minutes === "number") {
+    config.sweepIntervalMinutes = raw.sweep_interval_minutes;
+  }
+  return Object.keys(config).length > 0 ? config : void 0;
+}
 
 // src/in-memory-deps.ts
 import { MemorySaver } from "@langchain/langgraph";
@@ -155,6 +187,27 @@ function embedInMemoryGraphs(graphs, overrides = {}) {
 }
 var createInMemoryDeps = embedInMemoryGraphs;
 
+// src/ttl-config.ts
+function resolveThreadTtl(raw) {
+  if (!raw) return void 0;
+  const ttl = {};
+  if (typeof raw.default_ttl === "number") ttl.defaultTtl = raw.default_ttl;
+  if (typeof raw.sweep_interval_minutes === "number") {
+    ttl.sweepIntervalMinutes = raw.sweep_interval_minutes;
+  }
+  return Object.keys(ttl).length > 0 ? ttl : void 0;
+}
+function resolveStoreTtl(raw) {
+  if (!raw) return void 0;
+  const ttl = {};
+  if (typeof raw.default_ttl === "number") ttl.defaultTtl = raw.default_ttl;
+  if (typeof raw.refresh_on_read === "boolean") ttl.refreshOnRead = raw.refresh_on_read;
+  if (typeof raw.sweep_interval_minutes === "number") {
+    ttl.sweepIntervalMinutes = raw.sweep_interval_minutes;
+  }
+  return Object.keys(ttl).length > 0 ? ttl : void 0;
+}
+
 // src/in-memory-runtime.ts
 function toGraphResolver(graphs) {
   return {
@@ -185,7 +238,14 @@ async function loadReloadableInMemoryRuntime(configPath, importModule, staticSch
     load: (graphId) => current.load(graphId),
     schemas: async (graphId) => await current.schemas(graphId)
   };
-  const store = new MemorySkeinStore2({ maxPageSize: resolveMaxPageSize() });
+  const threadTtl = resolveThreadTtl(first.config.checkpointer?.ttl);
+  const storeTtl = resolveStoreTtl(first.config.store?.ttl);
+  const idempotency = resolveIdempotency(first.config.skein?.idempotency);
+  const store = new MemorySkeinStore2({
+    maxPageSize: resolveMaxPageSize(),
+    ...threadTtl ? { threadTtl } : {},
+    ...storeTtl ? { ttl: storeTtl } : {}
+  });
   const checkpointer = new MemorySaver2();
   const deps = {
     store,
@@ -196,6 +256,10 @@ async function loadReloadableInMemoryRuntime(configPath, importModule, staticSch
     bus: new MemoryRunEventBus2(resolveMemoryBusLimits()),
     checkpointer,
     auth: await loadAuthEngine(first.config.auth, { configDir: first.configDir, importModule }),
+    // Present only when configured — its presence is what starts the thread TTL sweeper.
+    ...threadTtl ? { threadTtl } : {},
+    // Unlike `threadTtl`, absence here means *defaults*, not *off*: the header is honoured either way.
+    ...idempotency ? { idempotency } : {},
     ...extraDeps
   };
   return {
@@ -226,12 +290,16 @@ export {
   corsFromHttpConfig,
   disabledRoutesFromHttpConfig,
   routesFromHttpConfig,
+  consoleMountFromHttpConfig,
+  resolveIdempotency,
   resolveMaxPageSize,
   resolveMemoryBusLimits,
   normalizeEmbeddableGraphs,
   graphMapToResolver,
   embedInMemoryGraphs,
   createInMemoryDeps,
+  resolveThreadTtl,
+  resolveStoreTtl,
   loadInMemoryRuntime,
   loadReloadableInMemoryRuntime
 };

package/dist/{in-memory-runtime-32UYJRVJ.js → in-memory-runtime-BUUSE63C.js}

@@ -1,7 +1,7 @@
 import {
   loadInMemoryRuntime,
   loadReloadableInMemoryRuntime
-} from "./chunk-QOHYARHD.js";
+} from "./chunk-XDS3YWFL.js";
 import "./chunk-JUBBCC7R.js";
 export {
   loadInMemoryRuntime,

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ProtocolRuntime, RouteBinding, Logger, ProtocolDeps, RunWorkerOptions, CronSchedulerOptions, RunFailureReport, GraphResolver, RouteMatcher, DisabledRouteGroups, ProtocolResponse } from '@skein-js/agent-protocol';
+import { ProtocolRuntime, RouteBinding, Logger, ProtocolDeps, RunWorkerOptions, CronSchedulerOptions, RunFailureReport, IdempotencyConfig, GraphResolver, RouteMatcher, DisabledRouteGroups, ProtocolResponse } from '@skein-js/agent-protocol';
 export { CompiledGraphFactory, DEFAULT_RUN_CONCURRENCY, DEFAULT_SHUTDOWN_GRACE_MS, GraphResolver, Logger, ProtocolDeps, ResolvedGraph, RunWorkerOptions } from '@skein-js/agent-protocol';
 import { ModuleImporter, LanggraphJson, GraphSchemas } from '@skein-js/config';
 import { CorsOptions } from 'cors';
@@ -6,9 +6,9 @@ export { CorsOptions } from 'cors';
 import { MemoryRunEventBusOptions } from '@skein-js/storage-memory';
 import { D as DevStateSnapshot } from './dev-BfYYRfEB.js';
 export { a as DevStateCounts } from './dev-BfYYRfEB.js';
+import { StoreTtlConfig, ThreadTtlConfig } from '@skein-js/core';
 import { CompiledGraph } from '@langchain/langgraph';
 import { ServerResponse } from 'node:http';
-import '@skein-js/core';
 
 interface SkeinRuntimeCommonOptions {
     /**
@@ -454,6 +454,49 @@ declare function loadReloadableInMemoryRuntime(configPath: string, importModule?
  */
 extraDeps?: Partial<Omit<ProtocolDeps, "graphs">>): Promise<ReloadableInMemoryRuntime>;
 
+/** The raw `checkpointer.ttl` block as `langgraph.json` spells it. */
+interface RawThreadTtl {
+    default_ttl?: number;
+    strategy?: "delete";
+    sweep_interval_minutes?: number;
+}
+/**
+ * Map the raw block to {@link ThreadTtlConfig}, or `undefined` when nothing is set — so threads never
+ * expire unless asked to, and no sweeper is started.
+ *
+ * `strategy` is read only to be validated by the config schema: `"delete"` is the only thing an
+ * expired thread can become, so there is nothing for the drivers to branch on.
+ */
+declare function resolveThreadTtl(raw: RawThreadTtl | undefined): ThreadTtlConfig | undefined;
+/** The raw `store.ttl` block as `langgraph.json` spells it. */
+interface RawStoreTtl {
+    default_ttl?: number;
+    refresh_on_read?: boolean;
+    sweep_interval_minutes?: number;
+}
+/**
+ * Map the raw `store.ttl` block to {@link StoreTtlConfig}, or `undefined` when nothing is set — so
+ * store items never expire unless asked to.
+ */
+declare function resolveStoreTtl(raw: RawStoreTtl | undefined): StoreTtlConfig | undefined;
+
+/** The raw `skein.idempotency` block as `langgraph.json` spells it. */
+interface RawIdempotency {
+    retention_hours?: number;
+    in_flight_minutes?: number;
+    sweep_interval_minutes?: number;
+}
+/**
+ * Map the raw block to {@link IdempotencyConfig}, or `undefined` when nothing is set.
+ *
+ * Note what `undefined` means here, because it differs from its neighbours: **defaults, not
+ * disabled.** `resolveStoreTtl` returning `undefined` genuinely means items never expire, but a
+ * caller who sends `Idempotency-Key` has been promised their retry will not start a second run —
+ * there is no configuration under which the header stops being honoured, only one that tunes how
+ * long the promise lasts.
+ */
+declare function resolveIdempotency(raw: RawIdempotency | undefined): IdempotencyConfig | undefined;
+
 type AnyCompiledGraph = CompiledGraph<any>;
 /**
  * A graph you can embed in code: any compiled LangGraph.js graph, or a factory that builds one per run
@@ -531,6 +574,17 @@ declare function disabledRoutesFromHttpConfig(http: unknown): DisabledRouteGroup
  * nothing is disabled (the same array, not a copy).
  */
 declare function routesFromHttpConfig(http: unknown): readonly RouteBinding[];
+/**
+ * Where the console should be mounted per a langgraph.json `http.console` block, or `undefined` for
+ * "do not serve it".
+ *
+ * Deliberately opt-in, and deliberately strict about what counts as opting in. The console can read
+ * and delete every thread, every stored memory, and every schedule on the server; a config that meant
+ * to disable it — a `"false"` left by env substitution, a `0`, a typo — must never be read as
+ * enabling it. `skein dev` does not go through here at all: it serves the console by default, because
+ * a local dev server is exactly where you want one.
+ */
+declare function consoleMountFromHttpConfig(http: unknown): string | undefined;
 
 type CorsSetting = true | CorsOptions;
 /**
@@ -649,4 +703,4 @@ type RuntimeGlobal = typeof globalThis & {
 /** Detect Node, Bun, or Deno without importing a runtime-specific module. */
 declare function detectRuntimeCapabilities(scope?: RuntimeGlobal): RuntimeCapabilities;
 
-export { type ConsoleLogLevel, type ConsoleLoggerOptions, type CorsSetting, DEFAULT_HEAP_SAMPLE_MS, DEFAULT_HEAP_WARN_PERCENT, DevStateSnapshot, type EmbeddableGraph, type FileReader, HEAP_REARM_MARGIN_PERCENT, HEAP_REARM_PERCENT, type HeapHeadroom, type HeapPressureContext, type HeapPressureMonitor, type HeapPressureMonitorOptions, type InMemoryRuntimeConfig, type IntervalHandle, type LanggraphCorsConfig, type ReloadableInMemoryRuntime, type ResolvedMemoryBusLimits, type ResolvedProtocolRuntime, type ResolvedRuntimeDeps, type RuntimeCapabilities, type RuntimeMemorySnapshot, type RuntimeSignalSubscription, type SkeinRuntimeCommonOptions, type SkeinRuntimeOptions, allowedOrigin, applyNodeCors, checkHeapHeadroom, corsFromHttpConfig, corsPreflightHeaders, corsResponseHeaders, createConsoleLogger, createInMemoryDeps, describeError, describeHeapHeadroom, describePoolPressure, detectRuntimeCapabilities, disabledRoutesFromHttpConfig, embedInMemoryGraphs, formatLogMeta, graphMapToResolver, joinList, loadInMemoryRuntime, loadReloadableInMemoryRuntime, normalizeEmbeddableGraphs, readContainerMemoryLimit, resolveCronTickMs, resolveHeapPressureOptions, resolveMaxPageSize, resolveMemoryBusLimits, resolveProtocolRuntime, resolveRunConcurrency, resolveRunTimeoutMs, resolveRuntimeDeps, resolveShutdownGraceMs, routeMatcherFor, routesFromHttpConfig, runFailureIdentity, sendNodeError, sendNodePreflight, sendNodeResponse, startHeapPressureMonitor, stripBasePath, toCorsOptions };
+export { type ConsoleLogLevel, type ConsoleLoggerOptions, type CorsSetting, DEFAULT_HEAP_SAMPLE_MS, DEFAULT_HEAP_WARN_PERCENT, DevStateSnapshot, type EmbeddableGraph, type FileReader, HEAP_REARM_MARGIN_PERCENT, HEAP_REARM_PERCENT, type HeapHeadroom, type HeapPressureContext, type HeapPressureMonitor, type HeapPressureMonitorOptions, type InMemoryRuntimeConfig, type IntervalHandle, type LanggraphCorsConfig, type RawIdempotency, type RawStoreTtl, type RawThreadTtl, type ReloadableInMemoryRuntime, type ResolvedMemoryBusLimits, type ResolvedProtocolRuntime, type ResolvedRuntimeDeps, type RuntimeCapabilities, type RuntimeMemorySnapshot, type RuntimeSignalSubscription, type SkeinRuntimeCommonOptions, type SkeinRuntimeOptions, allowedOrigin, applyNodeCors, checkHeapHeadroom, consoleMountFromHttpConfig, corsFromHttpConfig, corsPreflightHeaders, corsResponseHeaders, createConsoleLogger, createInMemoryDeps, describeError, describeHeapHeadroom, describePoolPressure, detectRuntimeCapabilities, disabledRoutesFromHttpConfig, embedInMemoryGraphs, formatLogMeta, graphMapToResolver, joinList, loadInMemoryRuntime, loadReloadableInMemoryRuntime, normalizeEmbeddableGraphs, readContainerMemoryLimit, resolveCronTickMs, resolveHeapPressureOptions, resolveIdempotency, resolveMaxPageSize, resolveMemoryBusLimits, resolveProtocolRuntime, resolveRunConcurrency, resolveRunTimeoutMs, resolveRuntimeDeps, resolveShutdownGraceMs, resolveStoreTtl, resolveThreadTtl, routeMatcherFor, routesFromHttpConfig, runFailureIdentity, sendNodeError, sendNodePreflight, sendNodeResponse, startHeapPressureMonitor, stripBasePath, toCorsOptions };

package/dist/index.js

@@ -1,4 +1,5 @@
 import {
+  consoleMountFromHttpConfig,
   corsFromHttpConfig,
   createInMemoryDeps,
   disabledRoutesFromHttpConfig,
@@ -9,11 +10,14 @@ import {
   normalizeEmbeddableGraphs,
   positiveIntegerFromEnv,
   requirePositiveInteger,
+  resolveIdempotency,
   resolveMaxPageSize,
   resolveMemoryBusLimits,
+  resolveStoreTtl,
+  resolveThreadTtl,
   routesFromHttpConfig,
   toCorsOptions
-} from "./chunk-QOHYARHD.js";
+} from "./chunk-XDS3YWFL.js";
 import "./chunk-JUBBCC7R.js";
 
 // src/resolve-runtime.ts
@@ -162,7 +166,7 @@ function resolveLogger(option, injected, frameworkLogger) {
   return option ?? frameworkLogger;
 }
 async function resolveRuntimeDeps(options, frameworkLogger) {
-  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 loaded = options.deps ? { deps: options.deps, cors: void 0, routes: skeinRoutes } : await (await import("./in-memory-runtime-BUUSE63C.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, routes: loaded.routes, logger };
@@ -653,6 +657,7 @@ export {
   allowedOrigin,
   applyNodeCors,
   checkHeapHeadroom,
+  consoleMountFromHttpConfig,
   corsFromHttpConfig,
   corsPreflightHeaders,
   corsResponseHeaders,
@@ -673,6 +678,7 @@ export {
   readContainerMemoryLimit,
   resolveCronTickMs,
   resolveHeapPressureOptions,
+  resolveIdempotency,
   resolveMaxPageSize,
   resolveMemoryBusLimits,
   resolveProtocolRuntime,
@@ -680,6 +686,8 @@ export {
   resolveRunTimeoutMs,
   resolveRuntimeDeps,
   resolveShutdownGraceMs,
+  resolveStoreTtl,
+  resolveThreadTtl,
   routeMatcherFor,
   routesFromHttpConfig,
   runFailureIdentity,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/server-kit",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Shared, framework-agnostic building blocks for skein-js HTTP adapters — in-memory dev runtime, LangGraph dev-state import, and langgraph.json CORS mapping.",
   "license": "Apache-2.0",
   "author": "Maina Wycliffe <wmmaina7@gmail.com>",
@@ -49,10 +49,10 @@
     "cors": "^2.8.5",
     "superjson": "^2.2.6",
     "zod": "^3.25.76",
-    "@skein-js/agent-protocol": "0.13.0",
-    "@skein-js/config": "0.13.0",
-    "@skein-js/core": "0.13.0",
-    "@skein-js/storage-memory": "0.13.0"
+    "@skein-js/agent-protocol": "0.14.0",
+    "@skein-js/config": "0.14.0",
+    "@skein-js/core": "0.14.0",
+    "@skein-js/storage-memory": "0.14.0"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0"