@skein-js/server-kit 0.9.0 → 0.10.0

package/README.md

@@ -75,7 +75,14 @@ Pass `overrides` to swap in production drivers or an auth engine while keeping t
   graph→`GraphResolver` helpers.
 - **`resolveProtocolRuntime(options): Promise<ResolvedProtocolRuntime>`** — turn a
   `{ config } | { deps }` bag (`SkeinRuntimeOptions`) into a live runtime (assistants seeded, worker
-  started) — the step every adapter runs before mounting routes.
+  started) — the step every adapter runs before mounting routes. `options.worker`
+  (`RunWorkerOptions`) tunes the background worker; `worker.maxConcurrency` is how many queued runs
+  run at once.
+- **`resolveRunConcurrency(explicit?, env?): number`** — the one precedence chain behind
+  `worker.maxConcurrency`: explicit value → `SKEIN_RUN_CONCURRENCY` → `N_JOBS_PER_WORKER` →
+  `DEFAULT_RUN_CONCURRENCY` (10, matching the LangGraph CLI). The environment is validated even when
+  an explicit value is given, so the two sources can't silently disagree. `skein dev`/`start` use it
+  to resolve the number they print in the startup banner.
 - **`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).

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { ProtocolRuntime, ProtocolDeps, Logger, GraphResolver, ProtocolResponse } from '@skein-js/agent-protocol';
-export { CompiledGraphFactory, GraphResolver, ProtocolDeps, ResolvedGraph } from '@skein-js/agent-protocol';
+import { ProtocolRuntime, ProtocolDeps, Logger, RunWorkerOptions, GraphResolver, ProtocolResponse } 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';
@@ -23,6 +23,23 @@ interface SkeinRuntimeCommonOptions {
      * server down.
      */
     warm?: boolean;
+    /**
+     * Background run-worker tuning. `maxConcurrency` is how many **queued** runs this instance executes
+     * at once (default `DEFAULT_RUN_CONCURRENCY`, matching the LangGraph CLI); omit it and skein reads
+     * `SKEIN_RUN_CONCURRENCY`, else the LangGraph-compatible `N_JOBS_PER_WORKER`. An explicit value
+     * wins, but the environment is still validated so the two sources can't silently disagree.
+     *
+     * Raising it never weakens per-thread ordering — two runs on one thread are still serialized by the
+     * 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;
 }
 /** Either point at a `langgraph.json` (in-memory runtime) or inject a ready `ProtocolDeps`. */
 type SkeinRuntimeOptions = SkeinRuntimeCommonOptions & ({
@@ -66,6 +83,32 @@ declare function resolveRuntimeDeps(options: SkeinRuntimeOptions): Promise<Resol
  */
 declare function resolveProtocolRuntime(options: SkeinRuntimeOptions): Promise<ResolvedProtocolRuntime>;
 
+/**
+ * The one precedence chain for background-run concurrency: an explicit value (a `worker.maxConcurrency`
+ * option, or the CLI's `--concurrency` / `-n`) wins, else `SKEIN_RUN_CONCURRENCY`, else
+ * `N_JOBS_PER_WORKER`, else {@link DEFAULT_RUN_CONCURRENCY}. The environment is read and validated
+ * even when `explicit` is given, so a bad `SKEIN_RUN_CONCURRENCY` can't sit unnoticed in a deployment
+ * that also passes the option.
+ *
+ * `env` is injected (defaulting to `process.env`) so callers — and tests — can resolve against an
+ * environment they control.
+ */
+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. */
@@ -235,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, 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

@@ -189,6 +189,55 @@ async function loadReloadableInMemoryRuntime(configPath, importModule, staticSch
   };
 }
 
+// src/run-concurrency.ts
+import { DEFAULT_RUN_CONCURRENCY } from "@skein-js/agent-protocol";
+import { SkeinConfigError } from "@skein-js/config";
+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);
+  if (explicit === void 0) return fromEnv ?? DEFAULT_RUN_CONCURRENCY;
+  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 };
@@ -197,7 +246,13 @@ async function resolveRuntimeDeps(options) {
 }
 async function resolveProtocolRuntime(options) {
   const { deps, cors: corsFromConfig } = await resolveRuntimeDeps(options);
-  const runtime = createProtocolRuntime(deps);
+  const runtime = createProtocolRuntime(deps, {
+    worker: {
+      ...options.worker,
+      maxConcurrency: resolveRunConcurrency(options.worker?.maxConcurrency),
+      shutdownGraceMs: resolveShutdownGraceMs(options.worker?.shutdownGraceMs)
+    }
+  });
   await runtime.service.assistants.registerGraphAssistants();
   if (options.warm) {
     await Promise.all(
@@ -212,6 +267,10 @@ async function resolveProtocolRuntime(options) {
   return { runtime, cors: corsFromConfig };
 }
 
+// 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";
@@ -651,6 +710,8 @@ function stripBasePath(pathname, basePath) {
   return null;
 }
 export {
+  DEFAULT_RUN_CONCURRENCY2 as DEFAULT_RUN_CONCURRENCY,
+  DEFAULT_SHUTDOWN_GRACE_MS2 as DEFAULT_SHUTDOWN_GRACE_MS,
   allowedOrigin,
   applyNodeCors,
   corsFromHttpConfig,
@@ -667,7 +728,9 @@ export {
   normalizeEmbeddableGraphs,
   readLanggraphDevState,
   resolveProtocolRuntime,
+  resolveRunConcurrency,
   resolveRuntimeDeps,
+  resolveShutdownGraceMs,
   sendNodeError,
   sendNodePreflight,
   sendNodeResponse,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/server-kit",
-  "version": "0.9.0",
+  "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/core": "0.9.0",
-    "@skein-js/agent-protocol": "0.9.0",
-    "@skein-js/config": "0.9.0",
-    "@skein-js/storage-memory": "0.9.0"
+    "@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"