@skein-js/express 0.1.0 → 0.2.1

package/README.md

@@ -1,38 +1,44 @@
 # @skein-js/express
 
-> Express adapter for skein-js — mount the Agent Protocol on an Express Router.
+> 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.
 
 ## What it does
 
-Converts Express `req`/`res` into [`@skein-js/agent-protocol`](../agent-protocol)'s normalized request, dispatches to its handler table, and pipes JSON / `204` / `text/event-stream` responses back out. Ships a `createExpressServer` convenience, a `skeinRouter` that returns a mountable `Router`, and the pure `createHandlerRouter` shim for callers wiring their own drivers.
+Converts Express `req`/`res` into [`@skein-js/agent-protocol`](../agent-protocol)'s normalized
+request, dispatches to its handler table, and pipes JSON / `204` / `text/event-stream` responses back
+out. It adds **no protocol logic of its own** — it's a thin transport shim. It ships:
 
-## Reuse
-
-Thin transport shim over [`@skein-js/agent-protocol`](../agent-protocol); adds no protocol logic of its own.
+- **`createExpressServer`** — a zero-setup server (reads a `langgraph.json`, wires in-memory drivers).
+- **`skeinRouter`** — a mountable `Router` for an existing Express app.
+- **`createHandlerRouter`** — the pure shim for callers wiring their own `ProtocolDeps`.
 
 ## Install
 
 ```bash
-pnpm add @skein-js/express
+pnpm add @skein-js/express @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
 
-The zero-setup server — reads a `langgraph.json`, wires in-memory drivers, and serves the Agent Protocol:
+The zero-setup server — reads a `langgraph.json`, wires in-memory drivers, and serves the protocol:
 
 ```ts
 import { createExpressServer } from "@skein-js/express";
 
 const server = await createExpressServer({ config: "./langgraph.json" });
-await server.listen(2024);
-// ...later: await server.close();
+await server.listen(2024); // defaults: port 2024, host "localhost"
+// …later:
+await server.close();
 ```
 
-Or mount the router on an existing Express app:
+Mount the router on an existing Express app:
 
 ```ts
 import express from "express";
@@ -45,15 +51,45 @@ app.listen(2024);
 // runtime.worker.stop() to drain background runs on shutdown.
 ```
 
-Bring your own persistent drivers (e.g. Postgres + Redis for `skein up`) through the same seam:
+Bring your own persistent drivers (e.g. Postgres + Redis, assembled by
+[`@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);
 ```
 
-### CORS
-
-Browser clients (Agent Chat UI, React `useStream`) run on a different origin. CORS is **off by default** (non-permissive) and driven by the `http.cors` block of `langgraph.json`, matching the LangGraph CLI:
+## API
+
+- **`createExpressServer(options): Promise<SkeinExpressServer>`** — `SkeinExpressServer` =
+  `{ app, runtime, listen(port?, host?), close() }`. `listen` defaults to port `2024`, host
+  `"localhost"`, resolves the Node `Server` once bound; `close()` stops the run worker then the HTTP
+  server (idempotent).
+- **`skeinRouter(options): Promise<SkeinRouter>`** — `SkeinRouter` = `{ router, runtime }`.
+- **`SkeinRouterOptions`** — common `{ logger?, cors?, warm? }` **plus** either `{ config, importModule? }`
+  (in-memory runtime from a `langgraph.json`) **or** `{ deps }` (bring-your-own `ProtocolDeps`).
+  `warm: true` eagerly loads graphs at startup; `logger` mounts per-request logging.
+- **`createHandlerRouter(handlers, options?)`** / **`skeinRoutes`** — the pure route table, for
+  composing your own routing over an existing `ProtocolHandlers`.
+- **`corsFromHttpConfig(http)`** / **`toCorsOptions(config)`** — map a `langgraph.json` `http.cors`
+  block onto `cors` options (`LanggraphCorsConfig`).
+- **`loadInMemoryRuntime` / `loadReloadableInMemoryRuntime`** — the in-memory `ProtocolDeps` loaders
+  (the reloadable one adds `reloadGraphs` / `snapshotState` / `hydrateState`, powering `skein dev`).
+- Low-level mappers: `toProtocolRequest`, `sendProtocolResponse`, `sendErrorResponse`.
+
+## CORS
+
+Browser clients (Agent Chat UI, React `useStream`) run on a different origin. CORS is **off by
+default** (non-permissive) and driven by the `http.cors` block of `langgraph.json`, matching the
+LangGraph CLI:
 
 ```jsonc
 {
@@ -62,13 +98,18 @@ Browser clients (Agent Chat UI, React `useStream`) run on a different origin. CO
 }
 ```
 
-Override in code with the `cors` option: pass [`CorsOptions`](https://github.com/expressjs/cors#configuration-options) to restrict origins, `true` for permissive dev, or `false` to force it off.
+Override in code with the `cors` option: pass [`CorsOptions`](https://github.com/expressjs/cors#configuration-options)
+to restrict origins, `true` for permissive dev, or `false` to force it off.
+
+## Reuse
+
+Thin transport shim over [`@skein-js/agent-protocol`](../agent-protocol); adds no protocol logic of
+its own.
 
 ## Learn more
 
-- [skein-js overview](../../docs/index.md)
-- [Reuse-first architecture](../../docs/reuse.md)
-- [Roadmap](../../docs/roadmap.md)
+- [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) · [Root README](../../README.md)
 
 ## License
 

package/package.json

@@ -1,19 +1,20 @@
 {
   "name": "@skein-js/express",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Express adapter for skein-js — mount the Agent Protocol on an Express Router.",
   "license": "Apache-2.0",
   "author": "Maina Wycliffe <wmmaina7@gmail.com>",
-  "homepage": "https://github.com/mainawycliffe/skein/tree/main/packages/server-express#readme",
+  "homepage": "https://github.com/mainawycliffe/skein-js/tree/main/packages/server-express#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/mainawycliffe/skein.git",
+    "url": "git+https://github.com/mainawycliffe/skein-js.git",
     "directory": "packages/server-express"
   },
   "bugs": {
-    "url": "https://github.com/mainawycliffe/skein/issues"
+    "url": "https://github.com/mainawycliffe/skein-js/issues"
   },
   "keywords": [
+    "typescript",
     "express",
     "langgraph",
     "agent-protocol",
@@ -40,10 +41,10 @@
   },
   "dependencies": {
     "cors": "^2.8.5",
-    "@skein-js/agent-protocol": "0.1.0",
-    "@skein-js/config": "0.1.0",
-    "@skein-js/core": "0.1.0",
-    "@skein-js/storage-memory": "0.1.0"
+    "@skein-js/agent-protocol": "0.2.1",
+    "@skein-js/core": "0.2.1",
+    "@skein-js/storage-memory": "0.2.1",
+    "@skein-js/config": "0.2.1"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0",