@skein-js/server-kit 0.13.1 → 0.14.1

package/dist/{chunk-LJGZJ5L7.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";
@@ -208,6 +240,7 @@ async function loadReloadableInMemoryRuntime(configPath, importModule, staticSch
   };
   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 } : {},
@@ -225,6 +258,8 @@ async function loadReloadableInMemoryRuntime(configPath, importModule, staticSch
     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 {
@@ -255,6 +290,8 @@ export {
   corsFromHttpConfig,
   disabledRoutesFromHttpConfig,
   routesFromHttpConfig,
+  consoleMountFromHttpConfig,
+  resolveIdempotency,
   resolveMaxPageSize,
   resolveMemoryBusLimits,
   normalizeEmbeddableGraphs,

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

@@ -1,7 +1,7 @@
 import {
   loadInMemoryRuntime,
   loadReloadableInMemoryRuntime
-} from "./chunk-LJGZJ5L7.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';
@@ -480,6 +480,23 @@ interface RawStoreTtl {
  */
 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
@@ -557,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;
 /**
@@ -675,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 RawStoreTtl, type RawThreadTtl, 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, resolveStoreTtl, resolveThreadTtl, 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,13 +10,14 @@ import {
   normalizeEmbeddableGraphs,
   positiveIntegerFromEnv,
   requirePositiveInteger,
+  resolveIdempotency,
   resolveMaxPageSize,
   resolveMemoryBusLimits,
   resolveStoreTtl,
   resolveThreadTtl,
   routesFromHttpConfig,
   toCorsOptions
-} from "./chunk-LJGZJ5L7.js";
+} from "./chunk-XDS3YWFL.js";
 import "./chunk-JUBBCC7R.js";
 
 // src/resolve-runtime.ts
@@ -164,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-KII6KQ4U.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 };
@@ -655,6 +657,7 @@ export {
   allowedOrigin,
   applyNodeCors,
   checkHeapHeadroom,
+  consoleMountFromHttpConfig,
   corsFromHttpConfig,
   corsPreflightHeaders,
   corsResponseHeaders,
@@ -675,6 +678,7 @@ export {
   readContainerMemoryLimit,
   resolveCronTickMs,
   resolveHeapPressureOptions,
+  resolveIdempotency,
   resolveMaxPageSize,
   resolveMemoryBusLimits,
   resolveProtocolRuntime,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/server-kit",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "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/core": "0.13.1",
-    "@skein-js/storage-memory": "0.13.1",
-    "@skein-js/config": "0.13.1",
-    "@skein-js/agent-protocol": "0.13.1"
+    "@skein-js/config": "0.14.1",
+    "@skein-js/core": "0.14.1",
+    "@skein-js/agent-protocol": "0.14.1",
+    "@skein-js/storage-memory": "0.14.1"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0"