@skein-js/server-kit 0.9.1 → 0.11.1

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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';
-import { ModuleImporter, GraphSchemas } from '@skein-js/config';
+export { CompiledGraphFactory, DEFAULT_RUN_CONCURRENCY, DEFAULT_SHUTDOWN_GRACE_MS, GraphResolver, ProtocolDeps, ResolvedGraph, RunWorkerOptions } from '@skein-js/agent-protocol';
+import { ModuleImporter, LanggraphJson, GraphSchemas } from '@skein-js/config';
 import { CorsOptions } from 'cors';
 export { CorsOptions } from 'cors';
 import { MemoryStoreSnapshot } from '@skein-js/storage-memory';
@@ -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. */
@@ -116,6 +135,13 @@ interface InMemoryRuntimeConfig {
 /** Load `langgraph.json`, wiring fresh in-memory drivers and reading its `http.cors` for the adapter. */
 declare function loadInMemoryRuntime(configPath: string, importModule?: ModuleImporter, staticSchemas?: Record<string, GraphSchemas>): Promise<InMemoryRuntimeConfig>;
 interface ReloadableInMemoryRuntime extends InMemoryRuntimeConfig {
+    /**
+     * The parsed `langgraph.json`, so a caller that needs a block this runtime doesn't act on itself
+     * (`telemetry`, say) can read it without a second `loadConfig` — which would re-import every graph.
+     */
+    config: LanggraphJson;
+    /** Directory holding `langgraph.json`, for resolving paths declared relative to it. */
+    configDir: string;
     /**
      * Re-read the config and swap in freshly imported graphs, keeping the same drivers. Because the
      * run engine calls `graphs.load()` per run (it never caches the compiled graph itself), the next
@@ -134,7 +160,14 @@ interface ReloadableInMemoryRuntime extends InMemoryRuntimeConfig {
  * dev` pairs this with vite's watcher (clear vite's cache, then `reloadGraphs()` — no server
  * restart, no lost state) and with on-disk JSON persistence across restarts.
  */
-declare function loadReloadableInMemoryRuntime(configPath: string, importModule?: ModuleImporter, staticSchemas?: Record<string, GraphSchemas>): Promise<ReloadableInMemoryRuntime>;
+declare function loadReloadableInMemoryRuntime(configPath: string, importModule?: ModuleImporter, staticSchemas?: Record<string, GraphSchemas>, 
+/**
+ * Extra deps to build in, for a caller that acts on a config block this runtime doesn't itself
+ * read (`telemetry`). Merged **into** the constructed `deps`, so every consumer sees the same
+ * object — patching the returned `deps` afterwards would miss anything that already snapshotted it
+ * (`resolveDeps` spreads, it doesn't alias).
+ */
+extraDeps?: Partial<Omit<ProtocolDeps, "graphs">>): Promise<ReloadableInMemoryRuntime>;
 
 type AnyCompiledGraph = CompiledGraph<any>;
 /**
@@ -259,4 +292,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

@@ -153,7 +153,7 @@ async function loadInMemoryRuntime(configPath, importModule, staticSchemas) {
     cors: corsFromHttpConfig(config.http)
   };
 }
-async function loadReloadableInMemoryRuntime(configPath, importModule, staticSchemas) {
+async function loadReloadableInMemoryRuntime(configPath, importModule, staticSchemas, extraDeps) {
   const first = await loadConfig({ configPath, importModule, staticSchemas });
   let current = first.graphs;
   const graphs = {
@@ -169,11 +169,14 @@ async function loadReloadableInMemoryRuntime(configPath, importModule, staticSch
     queue: new MemoryRunQueue2(),
     bus: new MemoryRunEventBus2(),
     checkpointer,
-    auth: await loadAuthEngine(first.config.auth, { configDir: first.configDir, importModule })
+    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;
     },
@@ -214,6 +217,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 +252,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 +272,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 +714,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 +733,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.11.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>",
@@ -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.11.1",
+    "@skein-js/config": "0.11.1",
+    "@skein-js/core": "0.11.1",
+    "@skein-js/storage-memory": "0.11.1"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0"