@skein-js/server-kit 0.8.0 → 0.9.1

package/README.md

@@ -32,6 +32,8 @@ handler table.
   (an unset origin resolves to `*`, never a reflected origin, so it can't pair with credentials).
 - **Node transport** — `sendNodeResponse` / `sendNodeError`: serialize a `ProtocolResponse` (JSON / 204
   / SSE) onto a Node `ServerResponse`, shared by the NestJS + Next.js Pages Router adapters.
+- **Mount prefix** — `stripBasePath`: strip the path an adapter is mounted under before matching the
+  route table, for adapters that mount a catch-all and match by hand (NestJS, Next.js).
 
 > The route table itself (`skeinRoutes`) is **not** here — it lives with the engine in
 > [`@skein-js/agent-protocol`](../agent-protocol), since it references the handler names. Adapters
@@ -73,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).
@@ -85,6 +94,10 @@ Pass `overrides` to swap in production drivers or an auth engine while keeping t
   derive CORS headers for adapters without a CORS middleware of their own.
 - **Node transport** — `sendNodeResponse` / `sendNodeError` serialize a `ProtocolResponse`
   (JSON / 204 / SSE) onto a Node `ServerResponse`, shared by the NestJS + Next.js Pages Router adapters.
+- **`stripBasePath(pathname, basePath): string | null`** — the pathname relative to a mount prefix, or
+  `null` when the path is not under it (the caller passes those through untouched). The prefix may be
+  written any way the host wrote it (`api`, `/api`, `/api/`); an empty one passes everything through.
+  Needed only by adapters that mount a catch-all — Express/Fastify get this from their router.
 
 ## Learn more
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { ProtocolRuntime, Logger, ProtocolDeps, 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 & ({
@@ -44,6 +56,20 @@ interface ResolvedProtocolRuntime {
     /** CORS mapped from the config's `http.cors`, or `undefined` for the injected-`deps` path. */
     cors?: CorsOptions;
 }
+/** Just the dependencies behind a `{ config } | { deps }` bag — no runtime, no worker. */
+interface ResolvedRuntimeDeps {
+    deps: ProtocolDeps;
+    /** CORS mapped from the config's `http.cors`, or `undefined` for the injected-`deps` path. */
+    cors?: CorsOptions;
+}
+/**
+ * Resolve the `{ config } | { deps }` seam down to a `ProtocolDeps` — injected as-is, or fresh
+ * in-memory drivers loaded from a `langgraph.json`. This is the half of
+ * {@link resolveProtocolRuntime} that stops short of building the engine, so the simplified invoke
+ * surface (which needs only graphs + store) doesn't seed assistants or start a run worker it will
+ * never use.
+ */
+declare function resolveRuntimeDeps(options: SkeinRuntimeOptions): Promise<ResolvedRuntimeDeps>;
 /**
  * Build a `ProtocolRuntime` from adapter options: resolve `deps` (injected, or fresh in-memory
  * drivers from a `langgraph.json`), seed one assistant per declared graph, optionally warm the
@@ -52,6 +78,18 @@ interface ResolvedProtocolRuntime {
  */
 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. */
@@ -214,4 +252,11 @@ declare function sendNodeResponse(response: ProtocolResponse, res: ServerRespons
 /** Serialize a caught error onto the Node `res`, using the protocol status when the error carries one. */
 declare function sendNodeError(error: unknown, res: ServerResponse, logger?: Logger, adapterName?: string): void;
 
-export { type CorsSetting, type DevStateCounts, type DevStateSnapshot, type EmbeddableGraph, type InMemoryRuntimeConfig, type LanggraphCorsConfig, type ReloadableInMemoryRuntime, type ResolvedProtocolRuntime, type SkeinRuntimeCommonOptions, type SkeinRuntimeOptions, allowedOrigin, applyNodeCors, corsFromHttpConfig, corsPreflightHeaders, corsResponseHeaders, createInMemoryDeps, describeSnapshot, embedInMemoryGraphs, graphMapToResolver, joinList, loadInMemoryRuntime, loadReloadableInMemoryRuntime, loadSnapshotIntoStore, normalizeEmbeddableGraphs, readLanggraphDevState, resolveProtocolRuntime, sendNodeError, sendNodePreflight, sendNodeResponse, toCorsOptions };
+/**
+ * The pathname relative to `basePath`, or `null` when the path is not under the mount — which the
+ * caller should treat as "not ours" and pass through untouched, so the host app's own routes still
+ * resolve. An empty (or `/`) base path passes the pathname through unchanged.
+ */
+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 };

package/dist/index.js

@@ -189,18 +189,45 @@ 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 };
+  const loaded = await loadInMemoryRuntime(options.config, options.importModule);
+  return { deps: loaded.deps, cors: loaded.cors };
+}
 async function resolveProtocolRuntime(options) {
-  let deps;
-  let corsFromConfig;
-  if (options.deps) {
-    deps = options.deps;
-  } else {
-    const loaded = await loadInMemoryRuntime(options.config, options.importModule);
-    deps = loaded.deps;
-    corsFromConfig = loaded.cors;
-  }
-  const runtime = createProtocolRuntime(deps);
+  const { deps, cors: corsFromConfig } = await resolveRuntimeDeps(options);
+  const runtime = createProtocolRuntime(deps, {
+    worker: {
+      ...options.worker,
+      maxConcurrency: resolveRunConcurrency(options.worker?.maxConcurrency)
+    }
+  });
   await runtime.service.assistants.registerGraphAssistants();
   if (options.warm) {
     await Promise.all(
@@ -215,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";
@@ -639,7 +669,22 @@ function sendNodeError(error, res, logger, adapterName = "skein") {
   res.writeHead(500, { "content-type": "application/json" });
   res.end(JSON.stringify({ status: 500, message: "Internal Server Error" }));
 }
+
+// src/base-path.ts
+function normalizeBasePath(basePath) {
+  if (basePath === "" || basePath === "/") return "";
+  const withLeadingSlash = basePath.startsWith("/") ? basePath : `/${basePath}`;
+  return withLeadingSlash.replace(/\/+$/, "");
+}
+function stripBasePath(pathname, basePath) {
+  const prefix = normalizeBasePath(basePath);
+  if (prefix === "") return pathname;
+  if (pathname === prefix) return "/";
+  if (pathname.startsWith(`${prefix}/`)) return pathname.slice(prefix.length);
+  return null;
+}
 export {
+  DEFAULT_RUN_CONCURRENCY2 as DEFAULT_RUN_CONCURRENCY,
   allowedOrigin,
   applyNodeCors,
   corsFromHttpConfig,
@@ -656,8 +701,11 @@ export {
   normalizeEmbeddableGraphs,
   readLanggraphDevState,
   resolveProtocolRuntime,
+  resolveRunConcurrency,
+  resolveRuntimeDeps,
   sendNodeError,
   sendNodePreflight,
   sendNodeResponse,
+  stripBasePath,
   toCorsOptions
 };

package/package.json

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