@skein-js/server-kit 0.9.1 → 0.10.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ProtocolRuntime, ProtocolDeps, Logger, RunWorkerOptions, GraphResolver, ProtocolResponse } from '@skein-js/agent-protocol';
-export { CompiledGraphFactory, DEFAULT_RUN_CONCURRENCY, GraphResolver, ProtocolDeps, ResolvedGraph, RunWorkerOptions } from '@skein-js/agent-protocol';
+export { CompiledGraphFactory, DEFAULT_RUN_CONCURRENCY, DEFAULT_SHUTDOWN_GRACE_MS, GraphResolver, ProtocolDeps, ResolvedGraph, RunWorkerOptions } from '@skein-js/agent-protocol';
 import { ModuleImporter, GraphSchemas } from '@skein-js/config';
 import { CorsOptions } from 'cors';
 export { CorsOptions } from 'cors';
@@ -33,6 +33,11 @@ interface SkeinRuntimeCommonOptions {
      * engine's execution lock — but see the head-of-line note in docs/runs-and-redis.md if your workload
      * leans on `multitask_strategy: "enqueue"`. Ignored by the invoke-only surface, which starts no
      * worker.
+     *
+     * `shutdownGraceMs` is how long `worker.stop()` lets in-flight runs finish before aborting them
+     * (default `DEFAULT_SHUTDOWN_GRACE_MS`); omit it and skein reads `SKEIN_SHUTDOWN_GRACE_MS`, with
+     * the same explicit-wins-but-still-validated rule. Whatever forces the process to exit must wait
+     * longer than this, or the abort step never runs — see docs/deploy.md.
      */
     worker?: RunWorkerOptions;
 }
@@ -90,6 +95,20 @@ declare function resolveProtocolRuntime(options: SkeinRuntimeOptions): Promise<R
  */
 declare function resolveRunConcurrency(explicit?: number, env?: NodeJS.ProcessEnv): number;
 
+/**
+ * The one precedence chain for the shutdown drain window: an explicit `worker.shutdownGraceMs` wins,
+ * else `SKEIN_SHUTDOWN_GRACE_MS`, else {@link DEFAULT_SHUTDOWN_GRACE_MS}. The environment is read and
+ * validated even when `explicit` is given, so a bad value can't sit unnoticed in a deployment that
+ * also passes the option.
+ *
+ * Zero is allowed and means "abort in-flight runs immediately" — a legitimate choice for a fleet that
+ * relies on queue redelivery instead of draining.
+ *
+ * `env` is injected (defaulting to `process.env`) so callers — and tests — can resolve against an
+ * environment they control.
+ */
+declare function resolveShutdownGraceMs(explicit?: number, env?: NodeJS.ProcessEnv): number;
+
 /** 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. */
@@ -259,4 +278,4 @@ declare function sendNodeError(error: unknown, res: ServerResponse, logger?: Log
  */
 declare function stripBasePath(pathname: string, basePath: string): string | null;
 
-export { type CorsSetting, type DevStateCounts, type DevStateSnapshot, type EmbeddableGraph, type InMemoryRuntimeConfig, type LanggraphCorsConfig, type ReloadableInMemoryRuntime, type ResolvedProtocolRuntime, type ResolvedRuntimeDeps, type SkeinRuntimeCommonOptions, type SkeinRuntimeOptions, allowedOrigin, applyNodeCors, corsFromHttpConfig, corsPreflightHeaders, corsResponseHeaders, createInMemoryDeps, describeSnapshot, embedInMemoryGraphs, graphMapToResolver, joinList, loadInMemoryRuntime, loadReloadableInMemoryRuntime, loadSnapshotIntoStore, normalizeEmbeddableGraphs, readLanggraphDevState, resolveProtocolRuntime, resolveRunConcurrency, resolveRuntimeDeps, sendNodeError, sendNodePreflight, sendNodeResponse, stripBasePath, toCorsOptions };
+export { type CorsSetting, type DevStateCounts, type DevStateSnapshot, type EmbeddableGraph, type InMemoryRuntimeConfig, type LanggraphCorsConfig, type ReloadableInMemoryRuntime, type ResolvedProtocolRuntime, type ResolvedRuntimeDeps, type SkeinRuntimeCommonOptions, type SkeinRuntimeOptions, allowedOrigin, applyNodeCors, corsFromHttpConfig, corsPreflightHeaders, corsResponseHeaders, createInMemoryDeps, describeSnapshot, embedInMemoryGraphs, graphMapToResolver, joinList, loadInMemoryRuntime, loadReloadableInMemoryRuntime, loadSnapshotIntoStore, normalizeEmbeddableGraphs, readLanggraphDevState, resolveProtocolRuntime, resolveRunConcurrency, resolveRuntimeDeps, resolveShutdownGraceMs, sendNodeError, sendNodePreflight, sendNodeResponse, stripBasePath, toCorsOptions };

package/dist/index.js

@@ -214,6 +214,30 @@ function resolveRunConcurrency(explicit, env = process.env) {
   return requirePositiveInteger("worker.maxConcurrency", explicit);
 }
 
+// src/shutdown-grace.ts
+import { DEFAULT_SHUTDOWN_GRACE_MS } from "@skein-js/agent-protocol";
+import { SkeinConfigError as SkeinConfigError2 } from "@skein-js/config";
+var SHUTDOWN_GRACE_ENV_VAR = "SKEIN_SHUTDOWN_GRACE_MS";
+function requireNonNegativeInteger(source, raw) {
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new SkeinConfigError2(
+      `${source} must be a non-negative integer in milliseconds (got "${String(raw)}").`
+    );
+  }
+  return parsed;
+}
+function shutdownGraceFromEnv(env) {
+  const raw = env[SHUTDOWN_GRACE_ENV_VAR];
+  if (raw === void 0 || raw.trim() === "") return void 0;
+  return requireNonNegativeInteger(SHUTDOWN_GRACE_ENV_VAR, raw);
+}
+function resolveShutdownGraceMs(explicit, env = process.env) {
+  const fromEnv = shutdownGraceFromEnv(env);
+  if (explicit === void 0) return fromEnv ?? DEFAULT_SHUTDOWN_GRACE_MS;
+  return requireNonNegativeInteger("worker.shutdownGraceMs", explicit);
+}
+
 // src/resolve-runtime.ts
 async function resolveRuntimeDeps(options) {
   if (options.deps) return { deps: options.deps };
@@ -225,7 +249,8 @@ async function resolveProtocolRuntime(options) {
   const runtime = createProtocolRuntime(deps, {
     worker: {
       ...options.worker,
-      maxConcurrency: resolveRunConcurrency(options.worker?.maxConcurrency)
+      maxConcurrency: resolveRunConcurrency(options.worker?.maxConcurrency),
+      shutdownGraceMs: resolveShutdownGraceMs(options.worker?.shutdownGraceMs)
     }
   });
   await runtime.service.assistants.registerGraphAssistants();
@@ -244,6 +269,7 @@ async function resolveProtocolRuntime(options) {
 
 // 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";
@@ -685,6 +711,7 @@ function stripBasePath(pathname, basePath) {
 }
 export {
   DEFAULT_RUN_CONCURRENCY2 as DEFAULT_RUN_CONCURRENCY,
+  DEFAULT_SHUTDOWN_GRACE_MS2 as DEFAULT_SHUTDOWN_GRACE_MS,
   allowedOrigin,
   applyNodeCors,
   corsFromHttpConfig,
@@ -703,6 +730,7 @@ export {
   resolveProtocolRuntime,
   resolveRunConcurrency,
   resolveRuntimeDeps,
+  resolveShutdownGraceMs,
   sendNodeError,
   sendNodePreflight,
   sendNodeResponse,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/server-kit",
-  "version": "0.9.1",
+  "version": "0.10.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>",
@@ -27,7 +27,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "files": [
@@ -43,10 +44,10 @@
     "cors": "^2.8.5",
     "superjson": "^2.2.6",
     "zod": "^3.25.76",
-    "@skein-js/agent-protocol": "0.9.1",
-    "@skein-js/core": "0.9.1",
-    "@skein-js/storage-memory": "0.9.1",
-    "@skein-js/config": "0.9.1"
+    "@skein-js/agent-protocol": "0.10.0",
+    "@skein-js/config": "0.10.0",
+    "@skein-js/storage-memory": "0.10.0",
+    "@skein-js/core": "0.10.0"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0"