@skein-js/server-kit 0.6.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,43 @@
+# @skein-js/server-kit
+
+> Shared, framework-agnostic building blocks for skein-js HTTP adapters.
+
+Part of **[skein-js](../../README.md)** — a TypeScript [Agent Protocol](https://github.com/langchain-ai/agent-protocol) server for [LangGraph.js](https://github.com/langchain-ai/langgraphjs), and a drop-in replacement for the LangGraph CLI.
+
+This package is the common ground the framework adapters ([`@skein-js/express`](../server-express),
+[`@skein-js/fastify`](../server-fastify), [`@skein-js/nestjs`](../server-nestjs),
+[`@skein-js/nextjs`](../server-nextjs)) stand on — so no adapter has to depend on another (or on
+Express) just to reuse it. It holds the framework-agnostic pieces (runtime assembly, dev-state import,
+CORS, and the Node-`http` transport the Node-based adapters share); each adapter still writes only the
+thin request/response shim its framework needs over the [`@skein-js/agent-protocol`](../agent-protocol)
+handler table.
+
+## What's here
+
+- **Runtime resolution** — `resolveProtocolRuntime`: turn a `{ config } | { deps }` bag into a live
+  runtime (assistants seeded, worker started) — the step every adapter runs before mounting routes.
+- **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).
+- **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.
+- **CORS** — `corsFromHttpConfig` / `toCorsOptions` map a `langgraph.json` `http.cors` block to
+  `cors`-style `CorsOptions`; `allowedOrigin` / `corsResponseHeaders` / `applyNodeCors` /
+  `sendNodePreflight` derive CORS headers for the adapters without a CORS middleware of their own
+  (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.
+
+> 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
+> import it from there.
+
+## Learn more
+
+- [Building your own adapter](../../docs/building-an-adapter.md)
+- [skein-js overview](../../docs/index.md)
+
+## License
+
+[Apache-2.0](../../LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,169 @@
+import { ProtocolRuntime, Logger, ProtocolDeps, ProtocolResponse } 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 { SkeinStore } from '@skein-js/core';
+import { ServerResponse } from 'node:http';
+
+interface SkeinRuntimeCommonOptions {
+    logger?: Logger;
+    /**
+     * Cross-origin access for browser clients (Agent Chat UI, React `useStream`). When omitted, CORS is
+     * driven by the config's `http.cors` block (LangGraph-compatible) and is otherwise **off** — we do
+     * not default to LangGraph's permissive `origin: "*"`. `true` reflects the request origin (dev),
+     * `CorsOptions` restricts origins for production, `false` forces it off. An explicit value wins.
+     */
+    cors?: boolean | CorsOptions;
+    /**
+     * Eager-load every declared graph at boot instead of lazily on first request, so graph import
+     * errors surface at startup. Load failures are logged, not thrown, so one bad graph never takes the
+     * server down.
+     */
+    warm?: boolean;
+}
+/** Either point at a `langgraph.json` (in-memory runtime) or inject a ready `ProtocolDeps`. */
+type SkeinRuntimeOptions = SkeinRuntimeCommonOptions & ({
+    config: string;
+    /**
+     * How graph modules are imported for the in-memory runtime. Defaults to a native dynamic
+     * `import()`; `skein dev` injects a vite-backed importer for TypeScript graphs.
+     */
+    importModule?: ModuleImporter;
+    deps?: never;
+} | {
+    deps: ProtocolDeps;
+    config?: never;
+    importModule?: never;
+});
+interface ResolvedProtocolRuntime {
+    /** The wired runtime — assistants seeded and the background worker already started. */
+    runtime: ProtocolRuntime;
+    /** CORS mapped from the config's `http.cors`, or `undefined` for the injected-`deps` path. */
+    cors?: CorsOptions;
+}
+/**
+ * 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
+ * graphs, and start the background run worker. Returns the runtime plus any CORS derived from the
+ * config so the adapter can apply it. The caller owns shutdown (`runtime.worker.stop()`).
+ */
+declare function resolveProtocolRuntime(options: SkeinRuntimeOptions): Promise<ResolvedProtocolRuntime>;
+
+/** 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. */
+type SerializedCheckpointStorage = Record<string, Record<string, Record<string, SerializedCheckpointTuple>>>;
+/** `MemorySaver.writes` (key → taskId+idx → `[taskId, channel, blob]`) with the blob base64-encoded. */
+type SerializedCheckpointWrites = Record<string, Record<string, [string, string, string]>>;
+interface CheckpointerSnapshot {
+    storage: SerializedCheckpointStorage;
+    writes: SerializedCheckpointWrites;
+}
+/** A JSON-serializable snapshot of the whole in-memory dev runtime. */
+interface DevStateSnapshot {
+    version: 1;
+    store: MemoryStoreSnapshot;
+    checkpoints: CheckpointerSnapshot;
+}
+
+interface InMemoryRuntimeConfig {
+    /** In-memory `ProtocolDeps` (store, queue, bus, checkpointer) around the config's graphs. */
+    deps: ProtocolDeps;
+    /** CORS mapped from the config's `http.cors`, or `undefined` when none is declared. */
+    cors?: CorsOptions;
+}
+/** Load `langgraph.json`, wiring fresh in-memory drivers and reading its `http.cors` for the adapter. */
+declare function loadInMemoryRuntime(configPath: string, importModule?: ModuleImporter, staticSchemas?: Record<string, GraphSchemas>): Promise<InMemoryRuntimeConfig>;
+interface ReloadableInMemoryRuntime extends InMemoryRuntimeConfig {
+    /**
+     * Re-read the config and swap in freshly imported graphs, keeping the same drivers. Because the
+     * run engine calls `graphs.load()` per run (it never caches the compiled graph itself), the next
+     * run picks up the new code while every thread, run, checkpoint, and store item survives. This is
+     * what lets `skein dev` hot-reload graph source without dropping in-memory state.
+     */
+    reloadGraphs(): Promise<void>;
+    /** A JSON-serializable snapshot of all dev state (protocol store + checkpoints). */
+    snapshotState(): DevStateSnapshot;
+    /** Restore dev state from a {@link snapshotState} — call before the server starts serving. */
+    hydrateState(snapshot: DevStateSnapshot): void;
+}
+/**
+ * Like {@link loadInMemoryRuntime}, but the returned `deps.graphs` delegates to a swappable config
+ * registry so graphs can be reloaded in place, and it can snapshot/restore its dev state. `skein
+ * dev` pairs this with vite's watcher (clear vite's cache, then `reloadGraphs()` — no server
+ * restart, no lost state) and with on-disk JSON persistence across restarts.
+ */
+declare function loadReloadableInMemoryRuntime(configPath: string, importModule?: ModuleImporter, staticSchemas?: Record<string, GraphSchemas>): Promise<ReloadableInMemoryRuntime>;
+
+/**
+ * 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).
+ */
+declare function readLanggraphDevState(langgraphApiDir: string): Promise<DevStateSnapshot | null>;
+/** Row/checkpoint counts in a snapshot, for CLI + log summaries. */
+interface DevStateCounts {
+    assistants: number;
+    threads: number;
+    runs: number;
+    items: number;
+    /** Threads that carry graph checkpoint history. */
+    checkpointedThreads: number;
+}
+declare function describeSnapshot(snapshot: DevStateSnapshot): DevStateCounts;
+/**
+ * Load a `DevStateSnapshot` into a live store + checkpointer — the sink for importing into a real
+ * skein deployment (e.g. Postgres). Resource rows go through the driver's `restore` (ids +
+ * timestamps preserved, `ON CONFLICT DO NOTHING` so re-runs are safe); checkpoints — graph state +
+ * full history — are copied via the public checkpointer API. Throws if the store can't bulk-restore
+ * (both first-party drivers can); a custom driver must implement `restore` to be an import target.
+ */
+declare function loadSnapshotIntoStore(snapshot: DevStateSnapshot, store: SkeinStore, checkpointer: BaseCheckpointSaver): Promise<void>;
+
+/** The `http.cors` block of a langgraph.json — LangGraph's field names (snake_case). */
+interface LanggraphCorsConfig {
+    allow_origins?: string[];
+    allow_origin_regex?: string;
+    allow_methods?: string[];
+    allow_headers?: string[];
+    allow_credentials?: boolean;
+    expose_headers?: string[];
+    max_age?: number;
+}
+/** Translate a LangGraph `http.cors` config into `cors` middleware options. */
+declare function toCorsOptions(config: LanggraphCorsConfig): CorsOptions;
+/** Read `http.cors` from a langgraph.json `http` block, mapped to `CorsOptions`, or `undefined`. */
+declare function corsFromHttpConfig(http: unknown): CorsOptions | undefined;
+
+type CorsSetting = true | CorsOptions;
+/**
+ * Resolve the `Access-Control-Allow-Origin` value for a request origin, or `undefined` to deny.
+ * An unset `origin` resolves to `*` (matching the `cors`/`@fastify/cors` default) rather than
+ * reflecting the caller's origin, so it can never be paired with credentials into a wildcard bypass.
+ */
+declare function allowedOrigin(requestOrigin: string | undefined, cors: CorsSetting): string | undefined;
+/** Join a `string | string[]` option into a comma list, or `undefined` when absent. */
+declare function joinList(value: string | string[] | undefined): string | undefined;
+/** The CORS response headers to merge onto an actual (non-preflight) response. */
+declare function corsResponseHeaders(requestOrigin: string | undefined, cors: CorsSetting): Record<string, string>;
+/** The preflight response headers for an `OPTIONS` request. */
+declare function corsPreflightHeaders(requestOrigin: string | undefined, requestedHeaders: string | undefined, cors: CorsSetting): Record<string, string>;
+/** Set CORS headers on a Node response for an actual request (before the status line is written). */
+declare function applyNodeCors(reqHeaders: {
+    origin?: string | string[];
+    [key: string]: string | string[] | undefined;
+}, res: ServerResponse, cors: CorsSetting): void;
+/** Answer an `OPTIONS` preflight on a Node response with a 204 + CORS headers. */
+declare function sendNodePreflight(reqHeaders: {
+    origin?: string | string[];
+    "access-control-request-headers"?: string | string[];
+    [key: string]: string | string[] | undefined;
+}, res: ServerResponse, cors: CorsSetting): void;
+
+/** Write a `ProtocolResponse` back onto the Node `res`, streaming when it is an SSE response. */
+declare function sendNodeResponse(response: ProtocolResponse, res: ServerResponse): Promise<void>;
+/** 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 };

package/dist/index.js

@@ -0,0 +1,629 @@
+// src/resolve-runtime.ts
+import {
+  createProtocolRuntime
+} from "@skein-js/agent-protocol";
+
+// src/in-memory-runtime.ts
+import { MemorySaver } from "@langchain/langgraph";
+import {
+  loadAuthEngine,
+  loadConfig
+} from "@skein-js/config";
+import { MemoryRunEventBus, MemoryRunQueue, MemorySkeinStore } from "@skein-js/storage-memory";
+
+// src/cors-config.ts
+var ALWAYS_EXPOSED_HEADERS = ["content-location", "x-pagination-total"];
+function toCorsOptions(config) {
+  const options = {};
+  const allowAll = config.allow_origins?.includes("*") ?? false;
+  if (config.allow_origin_regex !== void 0) {
+    const pattern = new RegExp(`^(?:${config.allow_origin_regex})$`);
+    const listed = allowAll ? void 0 : new Set(config.allow_origins);
+    options.origin = (origin, callback) => callback(
+      null,
+      origin !== void 0 && (allowAll || pattern.test(origin) || (listed?.has(origin) ?? false))
+    );
+  } else if (config.allow_origins !== void 0) {
+    options.origin = allowAll ? "*" : config.allow_origins;
+  }
+  if (config.allow_methods !== void 0) options.methods = config.allow_methods;
+  if (config.allow_headers !== void 0) options.allowedHeaders = config.allow_headers;
+  if (config.allow_credentials !== void 0) options.credentials = config.allow_credentials;
+  if (config.max_age !== void 0) options.maxAge = config.max_age;
+  const exposed = /* @__PURE__ */ new Set([...ALWAYS_EXPOSED_HEADERS, ...config.expose_headers ?? []]);
+  options.exposedHeaders = [...exposed];
+  return options;
+}
+function corsFromHttpConfig(http) {
+  if (typeof http !== "object" || http === null) return void 0;
+  const cors = http.cors;
+  if (typeof cors !== "object" || cors === null) return void 0;
+  return toCorsOptions(cors);
+}
+
+// src/dev-persistence.ts
+var toBase64 = (bytes) => Buffer.from(bytes).toString("base64");
+var fromBase64 = (text) => new Uint8Array(Buffer.from(text, "base64"));
+var mapValues = (record, fn) => Object.fromEntries(Object.entries(record).map(([key, value]) => [key, fn(value)]));
+function snapshotCheckpointer(saver) {
+  return {
+    storage: mapValues(
+      saver.storage,
+      (namespaces) => mapValues(
+        namespaces,
+        (checkpoints) => mapValues(checkpoints, ([checkpoint, metadata, parentId]) => [
+          toBase64(checkpoint),
+          toBase64(metadata),
+          parentId
+        ])
+      )
+    ),
+    writes: mapValues(
+      saver.writes,
+      (taskWrites) => mapValues(taskWrites, ([taskId, channel, blob]) => [
+        taskId,
+        channel,
+        toBase64(blob)
+      ])
+    )
+  };
+}
+function hydrateCheckpointer(saver, snapshot) {
+  saver.storage = mapValues(
+    snapshot.storage,
+    (namespaces) => mapValues(
+      namespaces,
+      (checkpoints) => mapValues(
+        checkpoints,
+        ([checkpoint, metadata, parentId]) => [
+          fromBase64(checkpoint),
+          fromBase64(metadata),
+          parentId
+        ]
+      )
+    )
+  );
+  saver.writes = mapValues(
+    snapshot.writes,
+    (taskWrites) => mapValues(taskWrites, ([taskId, channel, blob]) => [
+      taskId,
+      channel,
+      fromBase64(blob)
+    ])
+  );
+}
+
+// src/in-memory-runtime.ts
+function toGraphResolver(graphs) {
+  return {
+    ids: graphs.ids,
+    load: (graphId) => graphs.load(graphId),
+    schemas: async (graphId) => await graphs.schemas(graphId)
+  };
+}
+function buildInMemoryDeps(graphs) {
+  return {
+    store: new MemorySkeinStore(),
+    graphs,
+    queue: new MemoryRunQueue(),
+    bus: new MemoryRunEventBus(),
+    checkpointer: new MemorySaver()
+  };
+}
+async function loadInMemoryRuntime(configPath, importModule, staticSchemas) {
+  const { graphs, config, configDir } = await loadConfig({
+    configPath,
+    importModule,
+    staticSchemas
+  });
+  const deps = buildInMemoryDeps(toGraphResolver(graphs));
+  deps.auth = await loadAuthEngine(config.auth, { configDir, importModule });
+  return {
+    deps,
+    cors: corsFromHttpConfig(config.http)
+  };
+}
+async function loadReloadableInMemoryRuntime(configPath, importModule, staticSchemas) {
+  const first = await loadConfig({ configPath, importModule, staticSchemas });
+  let current = first.graphs;
+  const graphs = {
+    ids: first.graphs.ids,
+    load: (graphId) => current.load(graphId),
+    schemas: async (graphId) => await current.schemas(graphId)
+  };
+  const store = new MemorySkeinStore();
+  const checkpointer = new MemorySaver();
+  const deps = {
+    store,
+    graphs,
+    queue: new MemoryRunQueue(),
+    bus: new MemoryRunEventBus(),
+    checkpointer,
+    auth: await loadAuthEngine(first.config.auth, { configDir: first.configDir, importModule })
+  };
+  return {
+    deps,
+    cors: corsFromHttpConfig(first.config.http),
+    reloadGraphs: async () => {
+      current = (await loadConfig({ configPath, importModule, staticSchemas })).graphs;
+    },
+    snapshotState: () => ({
+      version: 1,
+      store: store.snapshot(),
+      checkpoints: snapshotCheckpointer(checkpointer)
+    }),
+    hydrateState: (snapshot) => {
+      store.hydrate(snapshot.store);
+      hydrateCheckpointer(checkpointer, snapshot.checkpoints);
+    }
+  };
+}
+
+// src/resolve-runtime.ts
+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);
+  await runtime.service.assistants.registerGraphAssistants();
+  if (options.warm) {
+    await Promise.all(
+      deps.graphs.ids.map(
+        (graphId) => deps.graphs.load(graphId).catch((error) => {
+          options.logger?.warn(`Failed to warm graph "${graphId}".`, error);
+        })
+      )
+    );
+  }
+  runtime.worker.start();
+  return { runtime, cors: corsFromConfig };
+}
+
+// src/langgraph-import.ts
+import { readFile } from "fs/promises";
+import path from "path";
+import {
+  MemorySaver as MemorySaver2
+} from "@langchain/langgraph";
+import {
+  isTerminalRunStatus
+} from "@skein-js/core";
+import { SuperJSON } from "superjson";
+import { z } from "zod";
+var OPS_FILE = ".langgraphjs_ops.json";
+var STORE_FILE = ".langgraphjs_api.store.json";
+var CHECKPOINTER_FILE = ".langgraphjs_api.checkpointer.json";
+var langgraphSuperjson = new SuperJSON();
+langgraphSuperjson.registerCustom(
+  {
+    isApplicable: (value) => value instanceof Uint8Array,
+    serialize: (value) => Buffer.from(value).toString("base64"),
+    deserialize: (value) => new Uint8Array(Buffer.from(value, "base64"))
+  },
+  "Uint8Array"
+);
+var timestamp = z.union([z.date(), z.string()]).optional();
+var jsonObject = z.record(z.unknown());
+var langgraphAssistantSchema = z.object({
+  assistant_id: z.string(),
+  graph_id: z.string(),
+  name: z.string().optional(),
+  description: z.string().nullish(),
+  config: jsonObject.optional(),
+  context: z.unknown().optional(),
+  metadata: jsonObject.optional(),
+  version: z.number().optional(),
+  created_at: timestamp,
+  updated_at: timestamp
+}).passthrough();
+var langgraphAssistantVersionSchema = z.object({
+  assistant_id: z.string(),
+  version: z.number(),
+  graph_id: z.string(),
+  name: z.string().optional(),
+  description: z.string().nullish(),
+  config: jsonObject.optional(),
+  context: z.unknown().optional(),
+  metadata: jsonObject.optional(),
+  created_at: timestamp
+}).passthrough();
+var langgraphThreadSchema = z.object({
+  thread_id: z.string(),
+  status: z.string().optional(),
+  metadata: jsonObject.optional(),
+  values: jsonObject.optional(),
+  interrupts: jsonObject.optional(),
+  created_at: timestamp,
+  updated_at: timestamp
+}).passthrough();
+var langgraphRunSchema = z.object({
+  run_id: z.string(),
+  thread_id: z.string(),
+  assistant_id: z.string(),
+  status: z.string().optional(),
+  metadata: jsonObject.optional(),
+  multitask_strategy: z.string().nullish(),
+  kwargs: jsonObject.optional(),
+  created_at: timestamp,
+  updated_at: timestamp
+}).passthrough();
+var langgraphOpsSchema = z.object({
+  assistants: z.record(langgraphAssistantSchema).optional(),
+  assistant_versions: z.array(langgraphAssistantVersionSchema).optional(),
+  threads: z.record(langgraphThreadSchema).optional(),
+  runs: z.record(langgraphRunSchema).optional()
+}).passthrough();
+var langgraphStoreItemSchema = z.object({
+  namespace: z.array(z.string()),
+  key: z.string(),
+  value: jsonObject,
+  createdAt: timestamp,
+  updatedAt: timestamp
+}).passthrough();
+var langgraphStoreFileSchema = z.object({ data: z.map(z.string(), z.map(z.string(), langgraphStoreItemSchema)).optional() }).passthrough();
+var langgraphCheckpointerSchema = z.object({ storage: jsonObject, writes: jsonObject }).passthrough();
+async function readSuperjsonFile(filepath) {
+  let text;
+  try {
+    text = await readFile(filepath, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    return langgraphSuperjson.parse(text) ?? null;
+  } catch (error) {
+    throw new Error(
+      `Could not parse LangGraph state file "${filepath}": ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+function validateShape(schema, value, label) {
+  const result = schema.safeParse(value);
+  if (!result.success) {
+    const detail = result.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+    throw new Error(`Invalid LangGraph ${label}: ${detail}`);
+  }
+  return result.data;
+}
+function toIso(value, fallback) {
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "string") return value;
+  return fallback;
+}
+function toAssistant(row, now) {
+  return {
+    assistant_id: row.assistant_id,
+    graph_id: row.graph_id,
+    name: row.name ?? row.graph_id,
+    description: row.description ?? void 0,
+    config: row.config ?? {},
+    context: row.context ?? {},
+    metadata: row.metadata ?? {},
+    version: row.version ?? 1,
+    created_at: toIso(row.created_at, now),
+    updated_at: toIso(row.updated_at, now)
+  };
+}
+function toAssistantVersion(row, now) {
+  return {
+    assistant_id: row.assistant_id,
+    version: row.version,
+    graph_id: row.graph_id,
+    name: row.name ?? row.graph_id,
+    description: row.description ?? void 0,
+    config: row.config ?? {},
+    context: row.context ?? {},
+    metadata: row.metadata ?? {},
+    created_at: toIso(row.created_at, now)
+  };
+}
+function toThread(row, now) {
+  const createdAt = toIso(row.created_at, now);
+  const updatedAt = toIso(row.updated_at, createdAt);
+  return {
+    thread_id: row.thread_id,
+    status: row.status ?? "idle",
+    metadata: row.metadata ?? {},
+    values: row.values ?? {},
+    interrupts: row.interrupts ?? {},
+    created_at: createdAt,
+    updated_at: updatedAt,
+    state_updated_at: updatedAt
+  };
+}
+function toRun(row, now) {
+  const createdAt = toIso(row.created_at, now);
+  const status = row.status ?? "success";
+  return {
+    run_id: row.run_id,
+    thread_id: row.thread_id,
+    assistant_id: row.assistant_id,
+    status: isTerminalRunStatus(status) ? status : "error",
+    metadata: row.metadata ?? {},
+    multitask_strategy: row.multitask_strategy ?? null,
+    created_at: createdAt,
+    updated_at: toIso(row.updated_at, createdAt)
+  };
+}
+function toRunKwargs(kwargs) {
+  if (!kwargs) return {};
+  const {
+    input,
+    command,
+    config,
+    context,
+    stream_mode,
+    interrupt_before,
+    interrupt_after,
+    webhook
+  } = kwargs;
+  return {
+    input,
+    command,
+    config,
+    context,
+    stream_mode,
+    interrupt_before,
+    interrupt_after,
+    ...typeof webhook === "string" ? { webhook } : {}
+  };
+}
+async function readLanggraphDevState(langgraphApiDir) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const [opsRaw, storeRaw, checkpointerRaw] = await Promise.all([
+    readSuperjsonFile(path.join(langgraphApiDir, OPS_FILE)),
+    readSuperjsonFile(path.join(langgraphApiDir, STORE_FILE)),
+    readSuperjsonFile(path.join(langgraphApiDir, CHECKPOINTER_FILE))
+  ]);
+  if (!opsRaw && !storeRaw && !checkpointerRaw) return null;
+  const ops = opsRaw ? validateShape(langgraphOpsSchema, opsRaw, OPS_FILE) : null;
+  const storeFile = storeRaw ? validateShape(langgraphStoreFileSchema, storeRaw, STORE_FILE) : null;
+  const checkpointerFile = checkpointerRaw ? validateShape(langgraphCheckpointerSchema, checkpointerRaw, CHECKPOINTER_FILE) : null;
+  const runEntries = Object.entries(ops?.runs ?? {});
+  const items = [];
+  if (storeFile?.data) {
+    for (const namespaceItems of storeFile.data.values()) {
+      for (const stored of namespaceItems.values()) {
+        const item = {
+          namespace: stored.namespace,
+          key: stored.key,
+          value: stored.value,
+          createdAt: toIso(stored.createdAt, now),
+          updatedAt: toIso(stored.updatedAt, now)
+        };
+        items.push([JSON.stringify([stored.namespace, stored.key]), item]);
+      }
+    }
+  }
+  const store = {
+    assistants: Object.entries(ops?.assistants ?? {}).map(([id, row]) => [
+      id,
+      toAssistant(row, now)
+    ]),
+    assistantVersions: (ops?.assistant_versions ?? []).map((row) => [
+      JSON.stringify([row.assistant_id, row.version]),
+      toAssistantVersion(row, now)
+    ]),
+    threads: Object.entries(ops?.threads ?? {}).map(([id, row]) => [id, toThread(row, now)]),
+    runs: runEntries.map(([id, row]) => [id, toRun(row, now)]),
+    runKwargs: runEntries.map(([id, row]) => [id, toRunKwargs(row.kwargs)]),
+    items
+  };
+  let checkpoints = { storage: {}, writes: {} };
+  if (checkpointerFile) {
+    const saver = new MemorySaver2();
+    saver.storage = checkpointerFile.storage;
+    saver.writes = checkpointerFile.writes;
+    checkpoints = snapshotCheckpointer(saver);
+  }
+  return { version: 1, store, checkpoints };
+}
+function describeSnapshot(snapshot) {
+  return {
+    assistants: snapshot.store.assistants.length,
+    threads: snapshot.store.threads.length,
+    runs: snapshot.store.runs.length,
+    items: snapshot.store.items.length,
+    checkpointedThreads: Object.keys(snapshot.checkpoints.storage).length
+  };
+}
+function supportsRestore(store) {
+  return typeof store.restore === "function";
+}
+async function copyCheckpoints(snapshot, target) {
+  const source = new MemorySaver2();
+  hydrateCheckpointer(source, snapshot);
+  const tuples = [];
+  for await (const tuple of source.list({})) tuples.push(tuple);
+  tuples.reverse();
+  for (const tuple of tuples) {
+    const configurable = tuple.config.configurable ?? {};
+    const putConfig = {
+      configurable: {
+        thread_id: configurable.thread_id,
+        checkpoint_ns: configurable.checkpoint_ns ?? "",
+        // `put` reads `checkpoint_id` as the PARENT pointer; the child's own id is `checkpoint.id`.
+        checkpoint_id: tuple.parentConfig?.configurable?.checkpoint_id
+      }
+    };
+    const stored = await target.put(
+      putConfig,
+      tuple.checkpoint,
+      tuple.metadata ?? {},
+      tuple.checkpoint.channel_versions ?? {}
+    );
+    const writesByTask = /* @__PURE__ */ new Map();
+    for (const [taskId, channel, value] of tuple.pendingWrites ?? []) {
+      const writes = writesByTask.get(taskId) ?? [];
+      writes.push([channel, value]);
+      writesByTask.set(taskId, writes);
+    }
+    for (const [taskId, writes] of writesByTask) {
+      await target.putWrites(stored, writes, taskId);
+    }
+  }
+}
+async function loadSnapshotIntoStore(snapshot, store, checkpointer) {
+  if (!supportsRestore(store)) {
+    throw new Error(
+      "Target store does not support bulk import (no restore() method). Use the in-memory or Postgres driver, or implement restore() on your SkeinStore."
+    );
+  }
+  await store.restore(snapshot.store);
+  await copyCheckpoints(snapshot.checkpoints, checkpointer);
+}
+
+// src/cors-runtime.ts
+function allowedOrigin(requestOrigin, cors) {
+  const origin = cors === true ? true : cors.origin;
+  if (origin === true) return requestOrigin ?? "*";
+  if (origin === void 0 || origin === "*") return "*";
+  if (typeof origin === "string") return origin;
+  if (Array.isArray(origin)) {
+    return requestOrigin && origin.includes(requestOrigin) ? requestOrigin : void 0;
+  }
+  if (origin instanceof RegExp) {
+    const anchored = new RegExp(`^(?:${origin.source})$`, origin.flags.replace("g", ""));
+    return requestOrigin && anchored.test(requestOrigin) ? requestOrigin : void 0;
+  }
+  if (typeof origin === "function") {
+    let verdict;
+    origin(
+      requestOrigin,
+      (_err, allow) => {
+        verdict = allow;
+      }
+    );
+    if (verdict === true) return requestOrigin ?? "*";
+    if (typeof verdict === "string") return verdict;
+    return void 0;
+  }
+  return void 0;
+}
+function joinList(value) {
+  if (value === void 0) return void 0;
+  return [].concat(value).join(",");
+}
+function corsResponseHeaders(requestOrigin, cors) {
+  const allow = allowedOrigin(requestOrigin, cors);
+  if (allow === void 0) return {};
+  const headers = { "access-control-allow-origin": allow };
+  if (allow !== "*") headers["vary"] = "origin";
+  if (cors !== true && cors.credentials) headers["access-control-allow-credentials"] = "true";
+  const exposed = cors !== true ? joinList(cors.exposedHeaders) : void 0;
+  if (exposed) headers["access-control-expose-headers"] = exposed;
+  return headers;
+}
+function corsPreflightHeaders(requestOrigin, requestedHeaders, cors) {
+  const headers = corsResponseHeaders(requestOrigin, cors);
+  headers["access-control-allow-methods"] = (cors !== true ? joinList(cors.methods) : void 0) ?? "GET,POST,PUT,PATCH,DELETE,OPTIONS";
+  const allowedHeaders = (cors !== true ? joinList(cors.allowedHeaders) : void 0) ?? requestedHeaders;
+  if (allowedHeaders) headers["access-control-allow-headers"] = allowedHeaders;
+  if (cors !== true && typeof cors.maxAge === "number") {
+    headers["access-control-max-age"] = String(cors.maxAge);
+  }
+  return headers;
+}
+function firstHeader(value) {
+  return Array.isArray(value) ? value[0] : value;
+}
+function applyNodeCors(reqHeaders, res, cors) {
+  const headers = corsResponseHeaders(firstHeader(reqHeaders.origin), cors);
+  for (const [name, value] of Object.entries(headers)) res.setHeader(name, value);
+}
+function sendNodePreflight(reqHeaders, res, cors) {
+  const headers = corsPreflightHeaders(
+    firstHeader(reqHeaders.origin),
+    firstHeader(reqHeaders["access-control-request-headers"]),
+    cors
+  );
+  res.writeHead(204, headers).end();
+}
+
+// src/node-transport.ts
+import { SSE_HEADERS } from "@skein-js/agent-protocol";
+import { isSkeinHttpError, serializeWireJson } from "@skein-js/core";
+var ignoreStreamError = () => {
+};
+async function pipeServerSentEvents(status, events, res) {
+  res.writeHead(status, SSE_HEADERS);
+  res.flushHeaders();
+  const iterator = events[Symbol.asyncIterator]();
+  let clientDisconnected = false;
+  const releaseOnClientClose = () => {
+    clientDisconnected = true;
+    void Promise.resolve(iterator.return?.(void 0)).catch(ignoreStreamError);
+  };
+  res.once("close", releaseOnClientClose);
+  res.on("error", ignoreStreamError);
+  try {
+    for (; ; ) {
+      const next = await iterator.next();
+      if (next.done || clientDisconnected) break;
+      res.write(next.value);
+    }
+  } finally {
+    res.removeListener("close", releaseOnClientClose);
+    if (!res.writableEnded) res.end();
+  }
+}
+async function sendNodeResponse(response, res) {
+  switch (response.kind) {
+    case "json":
+      res.writeHead(response.status, { "content-type": "application/json" });
+      res.end(serializeWireJson(response.body));
+      return;
+    case "empty":
+      res.writeHead(response.status).end();
+      return;
+    case "sse":
+      await pipeServerSentEvents(response.status, response.events, res);
+      return;
+  }
+}
+function sendNodeError(error, res, logger, adapterName = "skein") {
+  if (res.headersSent) {
+    if (!isSkeinHttpError(error)) logger?.error("Unhandled error after headers were sent.", error);
+    if (!res.writableEnded) res.end();
+    return;
+  }
+  if (isSkeinHttpError(error)) {
+    res.writeHead(error.status, { "content-type": "application/json" });
+    res.end(
+      JSON.stringify({
+        status: error.status,
+        message: error.message,
+        ...error.code !== void 0 ? { code: error.code } : {},
+        ...error.details !== void 0 ? { details: error.details } : {}
+      })
+    );
+    return;
+  }
+  logger?.error(`Unhandled error in the ${adapterName} adapter.`, error);
+  res.writeHead(500, { "content-type": "application/json" });
+  res.end(JSON.stringify({ status: 500, message: "Internal Server Error" }));
+}
+export {
+  allowedOrigin,
+  applyNodeCors,
+  corsFromHttpConfig,
+  corsPreflightHeaders,
+  corsResponseHeaders,
+  describeSnapshot,
+  joinList,
+  loadInMemoryRuntime,
+  loadReloadableInMemoryRuntime,
+  loadSnapshotIntoStore,
+  readLanggraphDevState,
+  resolveProtocolRuntime,
+  sendNodeError,
+  sendNodePreflight,
+  sendNodeResponse,
+  toCorsOptions
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@skein-js/server-kit",
+  "version": "0.6.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>",
+  "homepage": "https://github.com/mainawycliffe/skein-js/tree/main/packages/server-kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mainawycliffe/skein-js.git",
+    "directory": "packages/server-kit"
+  },
+  "bugs": {
+    "url": "https://github.com/mainawycliffe/skein-js/issues"
+  },
+  "keywords": [
+    "typescript",
+    "langgraph",
+    "agent-protocol",
+    "adapter",
+    "cors"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "superjson": "^2.2.6",
+    "zod": "^3.25.76",
+    "@skein-js/config": "0.6.1",
+    "@skein-js/core": "0.6.1",
+    "@skein-js/storage-memory": "0.6.1",
+    "@skein-js/agent-protocol": "0.6.1"
+  },
+  "peerDependencies": {
+    "@langchain/langgraph": "^1.4.0"
+  },
+  "devDependencies": {
+    "@langchain/core": "^1.2.0",
+    "@langchain/langgraph": "^1.4.0",
+    "@types/cors": "^2.8.17"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}