@skein-js/server-kit 0.9.0 → 0.9.1

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, 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,18 @@ 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.
+     */
+    worker?: RunWorkerOptions;
 }
 /** Either point at a `langgraph.json` (in-memory runtime) or inject a ready `ProtocolDeps`. */
 type SkeinRuntimeOptions = SkeinRuntimeCommonOptions & ({
@@ -66,6 +78,18 @@ 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 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 +259,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, sendNodeError, sendNodePreflight, sendNodeResponse, stripBasePath, toCorsOptions };

package/dist/index.js

@@ -189,6 +189,31 @@ 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/resolve-runtime.ts
 async function resolveRuntimeDeps(options) {
   if (options.deps) return { deps: options.deps };
@@ -197,7 +222,12 @@ 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)
+    }
+  });
   await runtime.service.assistants.registerGraphAssistants();
   if (options.warm) {
     await Promise.all(
@@ -212,6 +242,9 @@ async function resolveProtocolRuntime(options) {
   return { runtime, cors: corsFromConfig };
 }
 
+// src/index.ts
+import { DEFAULT_RUN_CONCURRENCY as DEFAULT_RUN_CONCURRENCY2 } from "@skein-js/agent-protocol";
+
 // src/langgraph-import.ts
 import { readFile } from "fs/promises";
 import path from "path";
@@ -651,6 +684,7 @@ function stripBasePath(pathname, basePath) {
   return null;
 }
 export {
+  DEFAULT_RUN_CONCURRENCY2 as DEFAULT_RUN_CONCURRENCY,
   allowedOrigin,
   applyNodeCors,
   corsFromHttpConfig,
@@ -667,6 +701,7 @@ export {
   normalizeEmbeddableGraphs,
   readLanggraphDevState,
   resolveProtocolRuntime,
+  resolveRunConcurrency,
   resolveRuntimeDeps,
   sendNodeError,
   sendNodePreflight,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/server-kit",
-  "version": "0.9.0",
+  "version": "0.9.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>",
@@ -43,10 +43,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.9.1",
+    "@skein-js/core": "0.9.1",
+    "@skein-js/storage-memory": "0.9.1",
+    "@skein-js/config": "0.9.1"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0"