@skein-js/express 0.2.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 > Express adapter for skein-js — mount the Agent Protocol on an Express `Router`.
 
-Part of **[skein-js](https://github.com/mainawycliffe/skein)** — 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.
+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.
 
 **Status:** 🚧 Pre-alpha — implemented; the v1 framework adapter.
 
@@ -19,11 +19,11 @@ out. It adds **no protocol logic of its own** — it's a thin transport shim. It
 ## Install
 
 ```bash
-pnpm add @skein-js/express
+pnpm add @skein-js/express @langchain/langgraph
 ```
 
-Peer dependencies (install both in your project): **`express`** (`>=4.18`) and
-**`@langchain/langgraph`**.
+**`express`** (`>=4.18`) and **`@langchain/langgraph`** are peer dependencies. `express` is almost
+always already in your app; add it too if not (`pnpm add express`).
 
 ## Usage
 
@@ -52,10 +52,19 @@ app.listen(2024);
 ```
 
 Bring your own persistent drivers (e.g. Postgres + Redis, assembled by
-[`@skein-js/runtime`](../runtime)) through the same seam:
+[`@skein-js/runtime`](../runtime)) through the same `deps` seam:
 
 ```ts
-const { router } = await skeinRouter({ deps: myProtocolDeps });
+import { skeinRouter } from "@skein-js/express";
+import { buildRuntime } from "@skein-js/runtime";
+
+const runtime = await buildRuntime({
+  configPath: "./langgraph.json",
+  store: "postgres",
+  queue: "redis",
+});
+const { router } = await skeinRouter({ deps: runtime.deps, cors: runtime.cors });
+app.use(router);
 ```
 
 ## API
@@ -100,7 +109,7 @@ its own.
 ## Learn more
 
 - [Agent Protocol surface](../../docs/agent-protocol.md) · [Streaming (SSE)](../../docs/streaming.md) · [React SDK / `useStream`](../../docs/react-sdk.md)
-- [skein-js overview](../../docs/index.md) · [Reuse-first architecture](../../docs/reuse.md)
+- [skein-js overview](../../docs/index.md) · [Reuse-first architecture](../../docs/reuse.md) · [Root README](../../README.md)
 
 ## License
 

package/dist/index.d.ts

@@ -4,6 +4,8 @@ import { CorsOptions } from 'cors';
 import { Router, Express, Request, Response } from 'express';
 import { Server } from 'node:http';
 import { MemoryStoreSnapshot } from '@skein-js/storage-memory';
+import { BaseCheckpointSaver } from '@langchain/langgraph';
+import { SkeinStore } from '@skein-js/core';
 
 interface SkeinRouterCommonOptions {
     logger?: Logger;
@@ -150,6 +152,30 @@ interface ReloadableInMemoryRuntime extends InMemoryRuntimeConfig {
  */
 declare function loadReloadableInMemoryRuntime(configPath: string, importModule?: ModuleImporter): 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[];
@@ -165,4 +191,4 @@ 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;
 
-export { type DevStateSnapshot, type HandlerRouterOptions, type InMemoryRuntimeConfig, type LanggraphCorsConfig, type ReloadableInMemoryRuntime, type SkeinExpressServer, type SkeinRouter, type SkeinRouterOptions, corsFromHttpConfig, createExpressServer, createHandlerRouter, loadInMemoryRuntime, loadReloadableInMemoryRuntime, sendErrorResponse, sendProtocolResponse, skeinRouter, skeinRoutes, toCorsOptions, toProtocolRequest };
+export { type DevStateCounts, type DevStateSnapshot, type HandlerRouterOptions, type InMemoryRuntimeConfig, type LanggraphCorsConfig, type ReloadableInMemoryRuntime, type SkeinExpressServer, type SkeinRouter, type SkeinRouterOptions, corsFromHttpConfig, createExpressServer, createHandlerRouter, describeSnapshot, loadInMemoryRuntime, loadReloadableInMemoryRuntime, loadSnapshotIntoStore, readLanggraphDevState, sendErrorResponse, sendProtocolResponse, skeinRouter, skeinRoutes, toCorsOptions, toProtocolRequest };

package/dist/index.js

@@ -352,11 +352,14 @@ import express2 from "express";
 function requestLogger(logger) {
   return (req, res, next) => {
     const startedAt = Date.now();
+    logger.info(`<-- ${req.method} ${req.originalUrl}`);
     let logged = false;
     const log = () => {
       if (logged) return;
       logged = true;
-      logger.info(`${req.method} ${req.originalUrl} ${res.statusCode} ${Date.now() - startedAt}ms`);
+      logger.info(
+        `--> ${req.method} ${req.originalUrl} ${res.statusCode} ${Date.now() - startedAt}ms`
+      );
     };
     res.once("finish", log);
     res.once("close", log);
@@ -367,6 +370,9 @@ async function createExpressServer(options) {
   const { router, runtime } = await skeinRouter(options);
   const app = express2();
   if (options.logger) app.use(requestLogger(options.logger));
+  app.get("/ok", (_req, res) => {
+    res.json({ ok: true });
+  });
   app.use(router);
   let server;
   return {
@@ -389,12 +395,262 @@ async function createExpressServer(options) {
     }
   };
 }
+
+// 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 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(),
+  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 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 } = kwargs;
+  return { input, command, config, context, stream_mode, interrupt_before, interrupt_after };
+}
+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)
+    ]),
+    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);
+}
 export {
   corsFromHttpConfig,
   createExpressServer,
   createHandlerRouter,
+  describeSnapshot,
   loadInMemoryRuntime,
   loadReloadableInMemoryRuntime,
+  loadSnapshotIntoStore,
+  readLanggraphDevState,
   sendErrorResponse,
   sendProtocolResponse,
   skeinRouter,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/express",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Express adapter for skein-js — mount the Agent Protocol on an Express Router.",
   "license": "Apache-2.0",
   "author": "Maina Wycliffe <wmmaina7@gmail.com>",
@@ -41,10 +41,12 @@
   },
   "dependencies": {
     "cors": "^2.8.5",
-    "@skein-js/config": "0.2.0",
-    "@skein-js/core": "0.2.0",
-    "@skein-js/storage-memory": "0.2.0",
-    "@skein-js/agent-protocol": "0.2.0"
+    "superjson": "^2.2.6",
+    "zod": "^3.25.76",
+    "@skein-js/config": "0.3.0",
+    "@skein-js/agent-protocol": "0.3.0",
+    "@skein-js/storage-memory": "0.3.0",
+    "@skein-js/core": "0.3.0"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0",