@skein-js/express 0.1.0

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,75 @@
+# @skein-js/express
+
+> 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.
+
+**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.
+
+## Reuse
+
+Thin transport shim over [`@skein-js/agent-protocol`](../agent-protocol); adds no protocol logic of its own.
+
+## Install
+
+```bash
+pnpm add @skein-js/express
+```
+
+## Usage
+
+The zero-setup server — reads a `langgraph.json`, wires in-memory drivers, and serves the Agent Protocol:
+
+```ts
+import { createExpressServer } from "@skein-js/express";
+
+const server = await createExpressServer({ config: "./langgraph.json" });
+await server.listen(2024);
+// ...later: await server.close();
+```
+
+Or mount the router on an existing Express app:
+
+```ts
+import express from "express";
+import { skeinRouter } from "@skein-js/express";
+
+const app = express();
+const { router, runtime } = await skeinRouter({ config: "./langgraph.json" });
+app.use(router);
+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:
+
+```ts
+const { router } = await skeinRouter({ deps: myProtocolDeps });
+```
+
+### 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
+{
+  "graphs": { "agent": "./agent.ts:graph" },
+  "http": { "cors": { "allow_origins": ["http://localhost:3000"] } },
+}
+```
+
+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.
+
+## Learn more
+
+- [skein-js overview](../../docs/index.md)
+- [Reuse-first architecture](../../docs/reuse.md)
+- [Roadmap](../../docs/roadmap.md)
+
+## License
+
+[Apache-2.0](../../LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,168 @@
+import { ProtocolRuntime, Logger, ProtocolDeps, ProtocolHandlers, ProtocolRequest, ProtocolResponse } from '@skein-js/agent-protocol';
+import { ModuleImporter } from '@skein-js/config';
+import { CorsOptions } from 'cors';
+import { Router, Express, Request, Response } from 'express';
+import { Server } from 'node:http';
+import { MemoryStoreSnapshot } from '@skein-js/storage-memory';
+
+interface SkeinRouterCommonOptions {
+    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: "*"`. Set this to override: `CorsOptions` to
+     * restrict origins for `skein up`, `true` for permissive dev (reflect the request origin), or
+     * `false` to force it off. An explicit value wins over `http.cors`.
+     */
+    cors?: boolean | CorsOptions;
+    /**
+     * Eager-load every declared graph at boot instead of lazily on first request. `skein dev` sets
+     * this so (a) graph import errors surface at startup and (b) the graph source files enter the
+     * running process's module graph — which is what arms `tsx watch`'s hot reload (it only watches
+     * files that have actually been imported). Load failures are logged, not thrown, so one bad
+     * graph never takes the server down or breaks the watch loop.
+     */
+    warm?: boolean;
+}
+/** Either point at a `langgraph.json` (in-memory runtime) or inject a ready `ProtocolDeps`. */
+type SkeinRouterOptions = SkeinRouterCommonOptions & ({
+    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 SkeinRouter {
+    /** Mount on an Express app: `app.use(router)`. */
+    router: Router;
+    /** The wired runtime — call `runtime.worker.stop()` on shutdown to drain background runs. */
+    runtime: ProtocolRuntime;
+}
+/**
+ * Wire a protocol runtime and return its mountable router. Seeds one assistant per declared graph
+ * and starts the background run worker before returning, so the router is ready to serve.
+ */
+declare function skeinRouter(options: SkeinRouterOptions): Promise<SkeinRouter>;
+
+interface SkeinExpressServer {
+    /** The Express app, protocol mounted at `/`. Mount extra middleware or routes before `listen`. */
+    app: Express;
+    /** The wired runtime (assistants, handlers, worker). */
+    runtime: ProtocolRuntime;
+    /** Start listening; resolves with the Node `Server` once bound. Defaults to port 2024. */
+    listen(port?: number, host?: string): Promise<Server>;
+    /** Stop the run worker and close the HTTP server (if listening). */
+    close(): Promise<void>;
+}
+/** Build an Express server hosting the Agent Protocol, ready to `listen`. */
+declare function createExpressServer(options: SkeinRouterOptions): Promise<SkeinExpressServer>;
+
+type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
+interface RouteBinding {
+    method: HttpMethod;
+    path: string;
+    handler: keyof ProtocolHandlers;
+    /**
+     * Fold the path `thread_id` into the request body before dispatch. The SDK addresses a
+     * thread-scoped run by its path (`POST /threads/{id}/runs/stream`) while carrying only
+     * `assistant_id` in the body, but the stateless run handlers read `thread_id` from the body — so a
+     * thread-scoped mount must copy it across, or the run would target a stray new thread.
+     */
+    foldThreadIdIntoBody?: boolean;
+}
+/** The route table, ordered most-specific-first within each method so literals win over params. */
+declare const skeinRoutes: readonly RouteBinding[];
+interface HandlerRouterOptions {
+    /** Structured logger for unexpected (non-`SkeinHttpError`) faults. */
+    logger?: Logger;
+    /**
+     * Cross-origin access, needed by browser clients (Agent Chat UI, React `useStream`) that run on a
+     * different origin than the server. `true` reflects the request origin (permissive — good for
+     * `skein dev`); pass `CorsOptions` to restrict origins for `skein up`; omit/`false` to disable.
+     */
+    cors?: boolean | CorsOptions;
+}
+/**
+ * Build an Express `Router` that binds the route table to a handler table. This is the pure shim —
+ * it assembles no runtime and knows no storage driver, so callers can mount it over any
+ * `ProtocolHandlers` (in-memory for `skein dev`, Postgres + Redis for `skein up`).
+ */
+declare function createHandlerRouter(handlers: ProtocolHandlers, options?: HandlerRouterOptions): Router;
+
+/** Translate an Express `Request` into the normalized `ProtocolRequest` the handler table consumes. */
+declare function toProtocolRequest(req: Request): ProtocolRequest;
+
+/** Write a `ProtocolResponse` back onto the Express `res`, streaming when it is an SSE response. */
+declare function sendProtocolResponse(response: ProtocolResponse, res: Response): Promise<void>;
+
+/** Serialize a caught error onto `res`, using the protocol status when the error carries one. */
+declare function sendErrorResponse(error: unknown, res: Response, logger?: Logger): void;
+
+/** 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): 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): Promise<ReloadableInMemoryRuntime>;
+
+/** 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;
+
+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 };

package/dist/index.js

@@ -0,0 +1,404 @@
+// src/skein-router.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 cors2 = http.cors;
+  if (typeof cors2 !== "object" || cors2 === null) return void 0;
+  return toCorsOptions(cors2);
+}
+
+// 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) {
+  const { graphs, config, configDir } = await loadConfig({ configPath, importModule });
+  const deps = buildInMemoryDeps(toGraphResolver(graphs));
+  deps.auth = await loadAuthEngine(config.auth, { configDir, importModule });
+  return {
+    deps,
+    cors: corsFromHttpConfig(config.http)
+  };
+}
+async function loadReloadableInMemoryRuntime(configPath, importModule) {
+  const first = await loadConfig({ configPath, importModule });
+  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 })).graphs;
+    },
+    snapshotState: () => ({
+      version: 1,
+      store: store.snapshot(),
+      checkpoints: snapshotCheckpointer(checkpointer)
+    }),
+    hydrateState: (snapshot) => {
+      store.hydrate(snapshot.store);
+      hydrateCheckpointer(checkpointer, snapshot.checkpoints);
+    }
+  };
+}
+
+// src/routes.ts
+import cors from "cors";
+import express from "express";
+
+// src/error-response.ts
+import { isSkeinHttpError } from "@skein-js/core";
+function sendErrorResponse(error, res, logger) {
+  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.status(error.status).json({
+      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 skein Express adapter.", error);
+  res.status(500).json({ status: 500, message: "Internal Server Error" });
+}
+
+// src/send-protocol-response.ts
+import { SSE_HEADERS } from "@skein-js/agent-protocol";
+import { serializeWireJson } from "@skein-js/core";
+var ignoreStreamError = () => {
+};
+async function pipeServerSentEvents(status, events, res) {
+  res.status(status);
+  for (const [name, value] of Object.entries(SSE_HEADERS)) res.setHeader(name, value);
+  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 sendProtocolResponse(response, res) {
+  switch (response.kind) {
+    case "json":
+      res.status(response.status).type("application/json").send(serializeWireJson(response.body));
+      return;
+    case "empty":
+      res.status(response.status).end();
+      return;
+    case "sse":
+      await pipeServerSentEvents(response.status, response.events, res);
+      return;
+  }
+}
+
+// src/to-protocol-request.ts
+function toSingleValueHeaders(headers) {
+  const flattened = {};
+  for (const [name, value] of Object.entries(headers)) {
+    flattened[name] = Array.isArray(value) ? value[0] : value;
+  }
+  return flattened;
+}
+function toProtocolRequest(req) {
+  return {
+    method: req.method,
+    // Absolute URL so a synthesized WHATWG `Request` carries the path + query string; an auth
+    // handler may read either. `req.originalUrl` includes the query, unlike `req.path`.
+    url: `${req.protocol}://${req.get("host") ?? "localhost"}${req.originalUrl}`,
+    // Express 5 types params as `string | string[]`, but the protocol's routes use single named
+    // params only, so the narrower `Record<string, string>` holds.
+    params: req.params,
+    // Express parses the query string with `qs`; the handlers only read flat string / string[]
+    // values, so the parsed shape is compatible.
+    query: req.query,
+    body: req.body,
+    headers: toSingleValueHeaders(req.headers)
+  };
+}
+
+// src/routes.ts
+var skeinRoutes = [
+  // assistants
+  { method: "get", path: "/assistants/:assistant_id/schemas", handler: "getAssistantSchemas" },
+  { method: "get", path: "/assistants/:assistant_id", handler: "getAssistant" },
+  { method: "post", path: "/assistants/search", handler: "searchAssistants" },
+  // threads
+  { method: "post", path: "/threads/search", handler: "listThreads" },
+  { method: "post", path: "/threads", handler: "createThread" },
+  { method: "get", path: "/threads/:thread_id", handler: "getThread" },
+  { method: "patch", path: "/threads/:thread_id", handler: "patchThread" },
+  { method: "delete", path: "/threads/:thread_id", handler: "deleteThread" },
+  { method: "get", path: "/threads/:thread_id/state", handler: "getThreadState" },
+  { method: "post", path: "/threads/:thread_id/history", handler: "getThreadHistory" },
+  // runs — the stateless handlers are reused on the thread-scoped path with the id folded in
+  { method: "post", path: "/runs/wait", handler: "createWaitRun" },
+  { method: "post", path: "/runs/stream", handler: "createStreamRun" },
+  {
+    method: "post",
+    path: "/threads/:thread_id/runs/wait",
+    handler: "createWaitRun",
+    foldThreadIdIntoBody: true
+  },
+  {
+    method: "post",
+    path: "/threads/:thread_id/runs/stream",
+    handler: "createStreamRun",
+    foldThreadIdIntoBody: true
+  },
+  { method: "post", path: "/threads/:thread_id/runs", handler: "createBackgroundRun" },
+  { method: "get", path: "/threads/:thread_id/runs", handler: "listThreadRuns" },
+  { method: "post", path: "/threads/:thread_id/runs/:run_id/cancel", handler: "cancelRun" },
+  { method: "get", path: "/threads/:thread_id/runs/:run_id/stream", handler: "joinRunStream" },
+  { method: "get", path: "/threads/:thread_id/runs/:run_id", handler: "getRun" },
+  { method: "delete", path: "/threads/:thread_id/runs/:run_id", handler: "deleteRun" },
+  { method: "get", path: "/runs/:run_id/stream", handler: "joinRunStream" },
+  // thread streaming / commands
+  { method: "post", path: "/threads/:thread_id/stream", handler: "postThreadStream" },
+  { method: "get", path: "/threads/:thread_id/stream", handler: "getThreadStream" },
+  { method: "post", path: "/threads/:thread_id/commands", handler: "postThreadCommands" },
+  // store
+  { method: "put", path: "/store/items", handler: "putStoreItem" },
+  { method: "get", path: "/store/items", handler: "getStoreItem" },
+  { method: "delete", path: "/store/items", handler: "deleteStoreItem" },
+  { method: "post", path: "/store/items/search", handler: "searchStoreItems" },
+  { method: "post", path: "/store/namespaces", handler: "listStoreNamespaces" }
+];
+function foldThreadId(request) {
+  const threadId = request.params["thread_id"];
+  if (threadId === void 0) return request;
+  const base = typeof request.body === "object" && request.body !== null && !Array.isArray(request.body) ? request.body : {};
+  return { ...request, body: { ...base, thread_id: threadId } };
+}
+function createHandlerRouter(handlers, options = {}) {
+  const router = express.Router();
+  if (options.cors) router.use(cors(options.cors === true ? { origin: true } : options.cors));
+  router.use(express.json());
+  for (const binding of skeinRoutes) {
+    const invoke = handlers[binding.handler];
+    router[binding.method](binding.path, async (req, res) => {
+      try {
+        const request = toProtocolRequest(req);
+        const response = await invoke(binding.foldThreadIdIntoBody ? foldThreadId(request) : request);
+        await sendProtocolResponse(response, res);
+      } catch (error) {
+        sendErrorResponse(error, res, options.logger);
+      }
+    });
+  }
+  return router;
+}
+
+// src/skein-router.ts
+async function skeinRouter(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();
+  const router = createHandlerRouter(runtime.handlers, {
+    logger: options.logger,
+    // Explicit option wins; otherwise fall back to the config's `http.cors`, else off.
+    cors: options.cors ?? corsFromConfig ?? false
+  });
+  return { router, runtime };
+}
+
+// src/create-express-server.ts
+import express2 from "express";
+function requestLogger(logger) {
+  return (req, res, next) => {
+    const startedAt = Date.now();
+    let logged = false;
+    const log = () => {
+      if (logged) return;
+      logged = true;
+      logger.info(`${req.method} ${req.originalUrl} ${res.statusCode} ${Date.now() - startedAt}ms`);
+    };
+    res.once("finish", log);
+    res.once("close", log);
+    next();
+  };
+}
+async function createExpressServer(options) {
+  const { router, runtime } = await skeinRouter(options);
+  const app = express2();
+  if (options.logger) app.use(requestLogger(options.logger));
+  app.use(router);
+  let server;
+  return {
+    app,
+    runtime,
+    listen: (port = 2024, host = "localhost") => new Promise((resolve, reject) => {
+      const bound = app.listen(port, host, () => resolve(bound));
+      bound.once("error", reject);
+      server = bound;
+    }),
+    close: async () => {
+      await runtime.worker.stop();
+      const bound = server;
+      server = void 0;
+      if (bound) {
+        await new Promise((resolve, reject) => {
+          bound.close((error) => error ? reject(error) : resolve());
+        });
+      }
+    }
+  };
+}
+export {
+  corsFromHttpConfig,
+  createExpressServer,
+  createHandlerRouter,
+  loadInMemoryRuntime,
+  loadReloadableInMemoryRuntime,
+  sendErrorResponse,
+  sendProtocolResponse,
+  skeinRouter,
+  skeinRoutes,
+  toCorsOptions,
+  toProtocolRequest
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@skein-js/express",
+  "version": "0.1.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>",
+  "homepage": "https://github.com/mainawycliffe/skein/tree/main/packages/server-express#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mainawycliffe/skein.git",
+    "directory": "packages/server-express"
+  },
+  "bugs": {
+    "url": "https://github.com/mainawycliffe/skein/issues"
+  },
+  "keywords": [
+    "express",
+    "langgraph",
+    "agent-protocol",
+    "sse"
+  ],
+  "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",
+    "@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"
+  },
+  "peerDependencies": {
+    "@langchain/langgraph": "^1.4.0",
+    "express": ">=4.18.0"
+  },
+  "devDependencies": {
+    "@langchain/core": "^1.2.0",
+    "@langchain/langgraph": "^1.4.0",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "express": "^5.2.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}