@skein-js/agent-protocol 0.9.0 → 0.10.0

package/README.md

@@ -102,7 +102,10 @@ Graph **state, history, and interrupt/resume are 100% LangGraph-native** via the
 
 - **Entry points:** `createProtocolRuntime(deps, options?)` → `{ service, handlers, worker }`;
   `createProtocolService` / `createProtocolServiceFromContext`; `createProtocolHandlers`; `createContext`;
-  `createRunWorker(ctx, options?)` (`RunWorkerOptions`: `maxConcurrency`, `shutdownGraceMs`).
+  `createRunWorker(ctx, options?)` (`RunWorkerOptions`: `maxConcurrency` — queued runs at once,
+  default `DEFAULT_RUN_CONCURRENCY` (10, matching the LangGraph CLI) — and `shutdownGraceMs`). The
+  adapters surface this as `worker.maxConcurrency` and also read `SKEIN_RUN_CONCURRENCY` /
+  `N_JOBS_PER_WORKER`; see [runs-and-redis.md](../../docs/runs-and-redis.md#run-concurrency).
 - **Service surface** (`runtime.service`): `assistants` (`registerGraphAssistants`, `get`, `list`,
   `search`, `schemas`), `threads` (`create`/`get`/`list`/`patch`/`delete`/`history`/`getState`),
   `threadStream` (`stream` / `joinStream` / `command` — HIL resume, requires status `interrupted`),

package/dist/index.d.ts

@@ -436,10 +436,33 @@ interface ProtocolHandlers {
 }
 declare function createProtocolHandlers(service: ProtocolService): ProtocolHandlers;
 
+/**
+ * Queued runs one worker executes at once when nothing is configured. Matches the LangGraph CLI's
+ * `--n-jobs-per-worker` default, so a project moving off `langgraph dev` keeps its throughput.
+ */
+declare const DEFAULT_RUN_CONCURRENCY = 10;
+/**
+ * How long `stop()` lets in-flight runs finish before aborting them. Chosen to leave room inside the
+ * tightest common stop window — a container platform typically sends SIGTERM and SIGKILLs ~10s later
+ * (Cloud Run's default; `docker stop`'s too) — for this drain *plus* the abort-and-settle step that
+ * follows it. Raise it via `SKEIN_SHUTDOWN_GRACE_MS` where the platform allows a longer window
+ * (Railway, Kubernetes' `terminationGracePeriodSeconds`, ECS `stopTimeout`); the host must also wait
+ * longer than this before forcing exit, or the abort path never runs. See docs/deploy.md.
+ */
+declare const DEFAULT_SHUTDOWN_GRACE_MS = 5000;
 interface RunWorkerOptions {
-    /** Max runs executing at once. Default 1 — strict per-thread serialization in dev. */
+    /**
+     * Max queued runs this worker executes at once. Default {@link DEFAULT_RUN_CONCURRENCY}.
+     * Per-thread ordering does not depend on this: `startRunExecution` serializes by `thread_id` at
+     * every value. The trade-off is head-of-line blocking — a run waiting on a busy thread's lock
+     * still holds a slot, so a burst of `multitask_strategy: "enqueue"` runs on one thread can occupy
+     * the worker. See docs/runs-and-redis.md.
+     */
     maxConcurrency?: number;
-    /** How long `stop()` waits for in-flight runs before aborting them (ms). Default 5000. */
+    /**
+     * How long `stop()` waits for in-flight runs before aborting them (ms). Default
+     * {@link DEFAULT_SHUTDOWN_GRACE_MS}.
+     */
     shutdownGraceMs?: number;
 }
 interface RunWorker {
@@ -452,7 +475,7 @@ declare function createRunWorker(ctx: ProtocolContext, options?: RunWorkerOption
 
 /** Options for {@link createProtocolRuntime}. */
 interface ProtocolRuntimeOptions {
-    /** Tuning for the background run worker (concurrency, poll interval). */
+    /** Tuning for the background run worker (max concurrency, shutdown grace period). */
     worker?: RunWorkerOptions;
 }
 /** The wired engine: the service, the transport-neutral handler table, and the background worker. */
@@ -602,4 +625,4 @@ declare function toSseEvents(frames: AsyncIterable<RunFrame>, finalStatus: () =>
  */
 declare function parseAfterSeq(lastEventId: string | undefined): number;
 
-export { type AssistantService, type Clock, type CommandInput, type CompiledGraphFactory, type CreateAssistantInput, type CreateRunInput, type CreateThreadInput, DEFAULT_INVOKE_PREFIX, type DeleteAssistantOptions, type DrawGraphOptions, type GraphInvokeHandlerName, type GraphInvokeOptions, type GraphResolver, type GraphSchemas, type HistoryOptions, type HttpMethod, type Logger, type PatchThreadInput, type ProtocolContext, type ProtocolDeps, type ProtocolHandler, type ProtocolHandlers, type ProtocolRequest, type ProtocolResponse, type ProtocolRuntime, type ProtocolRuntimeOptions, type ProtocolService, type ResolvedGraph, type RouteBinding, type RouteMatch, type RouteMatcher, type RunService, type RunWorker, type RunWorkerOptions, SSE_HEADERS, SkeinBaseStore, type StartedStream, type StoreService, type SubgraphsOptions, type ThreadService, type ThreadStreamInput, type ThreadStreamService, buildProtocolService, copyThreadIdIntoBody, createContext, createGraphInvokeHandler, createProtocolHandlers, createProtocolRuntime, createProtocolService, createProtocolServiceFromContext, createRouteMatcher, createRunWorker, encodeFrame, encodeTerminal, foldThreadId, graphInvokeRoutes, matchSkeinRoute, parseAfterSeq, skeinRoutes, toSseEvents };
+export { type AssistantService, type Clock, type CommandInput, type CompiledGraphFactory, type CreateAssistantInput, type CreateRunInput, type CreateThreadInput, DEFAULT_INVOKE_PREFIX, DEFAULT_RUN_CONCURRENCY, DEFAULT_SHUTDOWN_GRACE_MS, type DeleteAssistantOptions, type DrawGraphOptions, type GraphInvokeHandlerName, type GraphInvokeOptions, type GraphResolver, type GraphSchemas, type HistoryOptions, type HttpMethod, type Logger, type PatchThreadInput, type ProtocolContext, type ProtocolDeps, type ProtocolHandler, type ProtocolHandlers, type ProtocolRequest, type ProtocolResponse, type ProtocolRuntime, type ProtocolRuntimeOptions, type ProtocolService, type ResolvedGraph, type RouteBinding, type RouteMatch, type RouteMatcher, type RunService, type RunWorker, type RunWorkerOptions, SSE_HEADERS, SkeinBaseStore, type StartedStream, type StoreService, type SubgraphsOptions, type ThreadService, type ThreadStreamInput, type ThreadStreamService, buildProtocolService, copyThreadIdIntoBody, createContext, createGraphInvokeHandler, createProtocolHandlers, createProtocolRuntime, createProtocolService, createProtocolServiceFromContext, createRouteMatcher, createRunWorker, encodeFrame, encodeTerminal, foldThreadId, graphInvokeRoutes, matchSkeinRoute, parseAfterSeq, skeinRoutes, toSseEvents };

package/dist/index.js

@@ -2014,7 +2014,15 @@ function createAuthorizingHandlers(context, engine) {
 import {
   isTerminalRunStatus as isTerminalRunStatus6
 } from "@skein-js/core";
-var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var DEFAULT_RUN_CONCURRENCY = 10;
+var DEFAULT_SHUTDOWN_GRACE_MS = 5e3;
+function cancellableDelay(ms) {
+  let timer;
+  const elapsed = new Promise((resolve) => {
+    timer = setTimeout(resolve, ms);
+  });
+  return { elapsed, cancel: () => clearTimeout(timer) };
+}
 function logRunLifecycle(logger, run, status, startedAt, endedAt) {
   logger.info(status === "success" ? "Background run succeeded" : `Background run ${status}`, {
     run_id: run.run_id,
@@ -2028,10 +2036,16 @@ function logRunLifecycle(logger, run, status, startedAt, endedAt) {
 }
 function createRunWorker(ctx, options = {}) {
   const { deps, control } = ctx;
-  const maxConcurrency = options.maxConcurrency ?? 1;
-  const shutdownGraceMs = options.shutdownGraceMs ?? 5e3;
+  const maxConcurrency = options.maxConcurrency ?? DEFAULT_RUN_CONCURRENCY;
+  const shutdownGraceMs = options.shutdownGraceMs ?? DEFAULT_SHUTDOWN_GRACE_MS;
   const inFlight = /* @__PURE__ */ new Set();
-  const process = async (queued) => {
+  const running = /* @__PURE__ */ new Set();
+  const executeQueuedRun = (queued) => {
+    const task = executeOne(queued);
+    running.add(task);
+    return task.finally(() => running.delete(task));
+  };
+  const executeOne = async (queued) => {
     const run = await deps.store.runs.get(queued.run_id);
     if (!run || isTerminalRunStatus6(run.status)) {
       ctx.rollbackPlans.delete(queued.run_id);
@@ -2052,20 +2066,37 @@ function createRunWorker(ctx, options = {}) {
   return {
     start() {
       if (consumer) return;
-      consumer = deps.queue.consume(process, { concurrency: maxConcurrency });
+      consumer = deps.queue.consume(executeQueuedRun, { concurrency: maxConcurrency });
     },
     async stop() {
       if (!consumer) return;
       const active = consumer;
       consumer = void 0;
       let drained = false;
-      const graceful = active.close().then(() => {
-        drained = true;
-      });
-      await Promise.race([graceful, sleep(shutdownGraceMs)]);
+      let drainFailure;
+      const graceful = active.close().then(
+        () => {
+          drained = true;
+        },
+        (error) => {
+          drainFailure = error;
+        }
+      );
+      const deadline = cancellableDelay(shutdownGraceMs);
+      try {
+        await Promise.race([graceful, deadline.elapsed]);
+      } finally {
+        deadline.cancel();
+      }
       if (!drained) {
         for (const runId of inFlight) control.abort(runId, "cancel");
         await graceful;
+        await Promise.allSettled([...running]);
+      }
+      if (drainFailure !== void 0) {
+        deps.logger.warn("Run queue did not close cleanly during shutdown", {
+          error: drainFailure instanceof Error ? drainFailure.message : String(drainFailure)
+        });
       }
     }
   };
@@ -2315,6 +2346,8 @@ function createGraphInvokeHandler(deps, options = {}) {
 }
 export {
   DEFAULT_INVOKE_PREFIX,
+  DEFAULT_RUN_CONCURRENCY,
+  DEFAULT_SHUTDOWN_GRACE_MS,
   SSE_HEADERS,
   SkeinBaseStore,
   buildProtocolService,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/agent-protocol",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Framework-agnostic Agent Protocol engine for LangGraph.js — run engine, handlers, and SSE, driven entirely by injected dependencies.",
   "license": "Apache-2.0",
   "author": "Maina Wycliffe <wmmaina7@gmail.com>",
@@ -30,7 +30,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "files": [
@@ -44,14 +45,14 @@
   },
   "dependencies": {
     "zod": "^3.25.76",
-    "@skein-js/core": "0.9.0"
+    "@skein-js/core": "0.10.0"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0",
     "@langchain/langgraph-sdk": "^1.9.0"
   },
   "devDependencies": {
-    "@skein-js/storage-memory": "0.9.0"
+    "@skein-js/storage-memory": "0.10.0"
   },
   "publishConfig": {
     "access": "public"