@skein-js/server-kit 0.6.3 → 0.8.0

package/README.md

@@ -19,6 +19,10 @@ handler table.
 - **In-memory dev runtime** — `loadInMemoryRuntime` / `loadReloadableInMemoryRuntime`: assemble a
   `ProtocolDeps` backed by in-process drivers from a `langgraph.json`. This is what powers `skein dev`
   and every adapter's `{ config }` convenience path (hot-reload + snapshot/restore included).
+- **In-code embedding** — `embedInMemoryGraphs` / `graphMapToResolver`: build a `ProtocolDeps` around a
+  compiled graph (or map of them) you already hold — **no `langgraph.json`, no CLI** — then pass
+  `{ deps }` to any adapter. `overrides` swaps in production drivers/auth. See
+  [docs/embedding.md](../../docs/embedding.md).
 - **LangGraph dev-state import** — `readLanggraphDevState` / `loadSnapshotIntoStore` /
   `describeSnapshot`: read an existing `.langgraph_api/` directory and reconstruct skein's own
   `DevStateSnapshot`, so adopting skein carries all local state over losslessly.
@@ -33,6 +37,55 @@ handler table.
 > [`@skein-js/agent-protocol`](../agent-protocol), since it references the handler names. Adapters
 > import it from there.
 
+## Install
+
+```bash
+pnpm add @skein-js/server-kit @langchain/langgraph
+```
+
+`@langchain/langgraph` is a peer dependency. You install this package directly when you **embed a
+graph in code** (`embedInMemoryGraphs`) or **write your own adapter**; the shipped adapters depend on
+it for you.
+
+## Usage
+
+The most common direct use is the in-code on-ramp — turn a compiled graph (or a map of them) into a
+`ProtocolDeps` and hand `{ deps }` to any adapter, with **no `langgraph.json` and no CLI**:
+
+```ts
+import { createExpressServer } from "@skein-js/express";
+import { embedInMemoryGraphs } from "@skein-js/server-kit";
+import { graph } from "./my-graph.js";
+
+const server = await createExpressServer({ deps: embedInMemoryGraphs({ agent: graph }) });
+await server.listen(2024);
+```
+
+Pass `overrides` to swap in production drivers or an auth engine while keeping the rest in-memory. See
+[docs/embedding.md](../../docs/embedding.md).
+
+## API
+
+- **`embedInMemoryGraphs(graphs, options?): ProtocolDeps`** — build a `ProtocolDeps` (store, queue,
+  bus, checkpointer) around a compiled graph or `Record<string, EmbeddableGraph>`. `options.overrides`
+  replaces any dep (e.g. a Postgres store, an `auth` engine). `createInMemoryDeps` is a
+  **`@deprecated`** alias. `graphMapToResolver` / `normalizeEmbeddableGraphs` are the lower-level
+  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.
+- **`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).
+- **`readLanggraphDevState` / `loadSnapshotIntoStore` / `describeSnapshot`** — read an existing
+  `.langgraph_api/` directory and reconstruct a `DevStateSnapshot`, so adopting skein carries local
+  state over losslessly.
+- **CORS** — `corsFromHttpConfig` / `toCorsOptions` map a `langgraph.json` `http.cors` block to
+  `cors`-style options; `allowedOrigin` / `corsResponseHeaders` / `applyNodeCors` / `sendNodePreflight`
+  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.
+
 ## Learn more
 
 - [Building your own adapter](../../docs/building-an-adapter.md)

package/dist/index.d.ts

@@ -1,9 +1,10 @@
-import { ProtocolRuntime, Logger, ProtocolDeps, ProtocolResponse } from '@skein-js/agent-protocol';
+import { ProtocolRuntime, Logger, ProtocolDeps, GraphResolver, ProtocolResponse } from '@skein-js/agent-protocol';
+export { CompiledGraphFactory, GraphResolver, ProtocolDeps, ResolvedGraph } from '@skein-js/agent-protocol';
 import { ModuleImporter, GraphSchemas } from '@skein-js/config';
 import { CorsOptions } from 'cors';
 export { CorsOptions } from 'cors';
 import { MemoryStoreSnapshot } from '@skein-js/storage-memory';
-import { BaseCheckpointSaver } from '@langchain/langgraph';
+import { CompiledGraph, BaseCheckpointSaver } from '@langchain/langgraph';
 import { SkeinStore } from '@skein-js/core';
 import { ServerResponse } from 'node:http';
 
@@ -97,6 +98,53 @@ interface ReloadableInMemoryRuntime extends InMemoryRuntimeConfig {
  */
 declare function loadReloadableInMemoryRuntime(configPath: string, importModule?: ModuleImporter, staticSchemas?: Record<string, GraphSchemas>): Promise<ReloadableInMemoryRuntime>;
 
+type AnyCompiledGraph = CompiledGraph<any>;
+/**
+ * A graph you can embed in code: any compiled LangGraph.js graph, or a factory that builds one per run
+ * (called with the run's `configurable`). Keys of a graph map become graph ids.
+ */
+type EmbeddableGraph = AnyCompiledGraph | ((config: {
+    configurable?: Record<string, unknown>;
+}) => AnyCompiledGraph | Promise<AnyCompiledGraph>);
+/**
+ * Accept either a ready {@link GraphResolver} or a plain graph map and return a `GraphResolver` either
+ * way — the normalization every in-code embedding helper shares (`embedInMemoryGraphs` here,
+ * `embedPostgresGraphs` in `@skein-js/runtime`), so the {@link isGraphResolver} discriminator lives in
+ * exactly one place.
+ */
+declare function normalizeEmbeddableGraphs(graphs: GraphResolver | Record<string, EmbeddableGraph>): GraphResolver;
+/**
+ * Turn a map of compiled graphs (or per-config factories) into a {@link GraphResolver}. Keys become the
+ * graph ids — one auto-registered assistant each. `schemas()` returns a minimal `{ graph_id }` stub:
+ * enough for the assistants introspection endpoints and everything `useStream` / Agent Chat UI render.
+ * Real input/output/state schema extraction stays a `langgraph.json`/config feature — it needs static
+ * TypeScript analysis of the graph source, which a compiled graph object no longer carries.
+ */
+declare function graphMapToResolver(graphs: Record<string, EmbeddableGraph>): GraphResolver;
+/**
+ * Build a `ProtocolDeps` backed by fresh in-process drivers (store, queue, bus, checkpointer) around
+ * graphs you already hold in code — no `langgraph.json`, no CLI. Pass a map of compiled graphs (or
+ * factories), or a ready {@link GraphResolver}. Hand the result to any adapter's `{ deps }` seam:
+ *
+ * ```ts
+ * import { embedInMemoryGraphs } from "@skein-js/server-kit";
+ * import { createExpressServer } from "@skein-js/express";
+ *
+ * createExpressServer({ deps: embedInMemoryGraphs({ myAgent: graph }) }).listen(2024);
+ * ```
+ *
+ * `overrides` replaces any driver or adds `auth`/`logger` — e.g. swap in a Postgres store + Redis
+ * queue for a durable, horizontally-scalable deployment. `graphs` is intentionally excluded from
+ * `overrides` (the first argument is the single source of graphs), so a stray `graphs` key can't
+ * silently void it.
+ */
+declare function embedInMemoryGraphs(graphs: GraphResolver | Record<string, EmbeddableGraph>, overrides?: Omit<Partial<ProtocolDeps>, "graphs">): ProtocolDeps;
+/**
+ * @deprecated Renamed to {@link embedInMemoryGraphs} — the function takes graphs and returns a
+ * `ProtocolDeps`, not a graph. Kept for back-compat; slated for removal in a future major.
+ */
+declare const createInMemoryDeps: typeof embedInMemoryGraphs;
+
 /**
  * Read a LangGraph `.langgraph_api/` directory and reconstruct skein's `DevStateSnapshot`.
  * Returns `null` when the directory holds none of the expected files (nothing to import).
@@ -166,4 +214,4 @@ 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 InMemoryRuntimeConfig, type LanggraphCorsConfig, type ReloadableInMemoryRuntime, type ResolvedProtocolRuntime, type SkeinRuntimeCommonOptions, type SkeinRuntimeOptions, allowedOrigin, applyNodeCors, corsFromHttpConfig, corsPreflightHeaders, corsResponseHeaders, describeSnapshot, joinList, loadInMemoryRuntime, loadReloadableInMemoryRuntime, loadSnapshotIntoStore, readLanggraphDevState, resolveProtocolRuntime, sendNodeError, sendNodePreflight, sendNodeResponse, toCorsOptions };
+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 };

package/dist/index.js

@@ -4,12 +4,12 @@ import {
 } from "@skein-js/agent-protocol";
 
 // src/in-memory-runtime.ts
-import { MemorySaver } from "@langchain/langgraph";
+import { MemorySaver as MemorySaver2 } from "@langchain/langgraph";
 import {
   loadAuthEngine,
   loadConfig
 } from "@skein-js/config";
-import { MemoryRunEventBus, MemoryRunQueue, MemorySkeinStore } from "@skein-js/storage-memory";
+import { MemoryRunEventBus as MemoryRunEventBus2, MemoryRunQueue as MemoryRunQueue2, MemorySkeinStore as MemorySkeinStore2 } from "@skein-js/storage-memory";
 
 // src/cors-config.ts
 var ALWAYS_EXPOSED_HEADERS = ["content-location", "x-pagination-total"];
@@ -93,21 +93,51 @@ function hydrateCheckpointer(saver, snapshot) {
   );
 }
 
-// src/in-memory-runtime.ts
-function toGraphResolver(graphs) {
+// src/in-memory-deps.ts
+import { MemorySaver } from "@langchain/langgraph";
+import { MemoryRunEventBus, MemoryRunQueue, MemorySkeinStore } from "@skein-js/storage-memory";
+function isGraphResolver(graphs) {
+  const candidate = graphs;
+  return Array.isArray(candidate.ids) && typeof candidate.load === "function";
+}
+function normalizeEmbeddableGraphs(graphs) {
+  return isGraphResolver(graphs) ? graphs : graphMapToResolver(graphs);
+}
+function graphMapToResolver(graphs) {
+  const ids = Object.keys(graphs);
   return {
-    ids: graphs.ids,
-    load: (graphId) => graphs.load(graphId),
-    schemas: async (graphId) => await graphs.schemas(graphId)
+    ids,
+    load: async (graphId) => {
+      const graph = graphs[graphId];
+      if (graph == null) {
+        const known = ids.join(", ") || "none";
+        throw new Error(
+          ids.includes(graphId) ? `Graph "${graphId}" resolved to ${String(graph)} \u2014 check its export/factory (known: ${known}).` : `Unknown graph "${graphId}" (known: ${known}).`
+        );
+      }
+      return graph;
+    },
+    schemas: async (graphId) => ({ [graphId]: { graph_id: graphId } })
   };
 }
-function buildInMemoryDeps(graphs) {
+function embedInMemoryGraphs(graphs, overrides = {}) {
   return {
     store: new MemorySkeinStore(),
-    graphs,
+    graphs: normalizeEmbeddableGraphs(graphs),
     queue: new MemoryRunQueue(),
     bus: new MemoryRunEventBus(),
-    checkpointer: new MemorySaver()
+    checkpointer: new MemorySaver(),
+    ...overrides
+  };
+}
+var createInMemoryDeps = embedInMemoryGraphs;
+
+// src/in-memory-runtime.ts
+function toGraphResolver(graphs) {
+  return {
+    ids: graphs.ids,
+    load: (graphId) => graphs.load(graphId),
+    schemas: async (graphId) => await graphs.schemas(graphId)
   };
 }
 async function loadInMemoryRuntime(configPath, importModule, staticSchemas) {
@@ -116,7 +146,7 @@ async function loadInMemoryRuntime(configPath, importModule, staticSchemas) {
     importModule,
     staticSchemas
   });
-  const deps = buildInMemoryDeps(toGraphResolver(graphs));
+  const deps = embedInMemoryGraphs(toGraphResolver(graphs));
   deps.auth = await loadAuthEngine(config.auth, { configDir, importModule });
   return {
     deps,
@@ -131,13 +161,13 @@ async function loadReloadableInMemoryRuntime(configPath, importModule, staticSch
     load: (graphId) => current.load(graphId),
     schemas: async (graphId) => await current.schemas(graphId)
   };
-  const store = new MemorySkeinStore();
-  const checkpointer = new MemorySaver();
+  const store = new MemorySkeinStore2();
+  const checkpointer = new MemorySaver2();
   const deps = {
     store,
     graphs,
-    queue: new MemoryRunQueue(),
-    bus: new MemoryRunEventBus(),
+    queue: new MemoryRunQueue2(),
+    bus: new MemoryRunEventBus2(),
     checkpointer,
     auth: await loadAuthEngine(first.config.auth, { configDir: first.configDir, importModule })
   };
@@ -189,7 +219,7 @@ async function resolveProtocolRuntime(options) {
 import { readFile } from "fs/promises";
 import path from "path";
 import {
-  MemorySaver as MemorySaver2
+  MemorySaver as MemorySaver3
 } from "@langchain/langgraph";
 import {
   isTerminalRunStatus
@@ -417,7 +447,7 @@ async function readLanggraphDevState(langgraphApiDir) {
   };
   let checkpoints = { storage: {}, writes: {} };
   if (checkpointerFile) {
-    const saver = new MemorySaver2();
+    const saver = new MemorySaver3();
     saver.storage = checkpointerFile.storage;
     saver.writes = checkpointerFile.writes;
     checkpoints = snapshotCheckpointer(saver);
@@ -437,7 +467,7 @@ function supportsRestore(store) {
   return typeof store.restore === "function";
 }
 async function copyCheckpoints(snapshot, target) {
-  const source = new MemorySaver2();
+  const source = new MemorySaver3();
   hydrateCheckpointer(source, snapshot);
   const tuples = [];
   for await (const tuple of source.list({})) tuples.push(tuple);
@@ -615,11 +645,15 @@ export {
   corsFromHttpConfig,
   corsPreflightHeaders,
   corsResponseHeaders,
+  createInMemoryDeps,
   describeSnapshot,
+  embedInMemoryGraphs,
+  graphMapToResolver,
   joinList,
   loadInMemoryRuntime,
   loadReloadableInMemoryRuntime,
   loadSnapshotIntoStore,
+  normalizeEmbeddableGraphs,
   readLanggraphDevState,
   resolveProtocolRuntime,
   sendNodeError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/server-kit",
-  "version": "0.6.3",
+  "version": "0.8.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>",
@@ -43,10 +43,10 @@
     "cors": "^2.8.5",
     "superjson": "^2.2.6",
     "zod": "^3.25.76",
-    "@skein-js/agent-protocol": "0.6.3",
-    "@skein-js/config": "0.6.3",
-    "@skein-js/core": "0.6.3",
-    "@skein-js/storage-memory": "0.6.3"
+    "@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"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0"