@skein-js/nestjs 0.7.0 → 0.9.0

package/README.md

@@ -31,10 +31,90 @@ export class AppModule {}
 ```
 
 The Agent Protocol is now served (`/threads`, `/assistants`, `/runs`, `/store`, …) alongside your
-routes. Pass `{ deps }` instead of `{ config }` to bring your own persistent drivers (Postgres +
-Redis) via [`@skein-js/runtime`](../runtime)'s `buildRuntime`. Call `app.enableCors(...)` as usual if
-browser clients run on another origin. Enable shutdown hooks (`app.enableShutdownHooks()`) so the
-background run worker drains on exit.
+routes. Call `app.enableCors(...)` as usual if browser clients run on another origin. Enable shutdown
+hooks (`app.enableShutdownHooks()`) so the background run worker drains on exit.
+
+### Serving under a global prefix
+
+If your app calls `app.setGlobalPrefix(...)`, the protocol follows it — there is nothing to configure
+on the skein side. Two things to do:
+
+**1. Set the prefix as you normally would**, and write your own controllers prefix-relative:
+
+```ts
+@Controller("todos") // Nest serves this at /api/todos
+class TodosController {}
+
+const app = await NestFactory.create(AppModule);
+app.setGlobalPrefix("api"); // the protocol moves to /api too
+await app.listen(2024);
+```
+
+**2. Point your client at the prefixed root** — not the server root:
+
+```ts
+const client = new Client({ apiUrl: "http://localhost:2024/api" });
+```
+
+That's it. `/api/threads`, `/api/assistants`, `/api/runs`, `/api/store/items` all serve, and requests
+that aren't skein's still fall through to your controllers.
+
+#### Still getting 404s?
+
+- **`Unsupported route path: "/api/*"` in your boot log** — expected and harmless. Nest logs it while
+  auto-converting the adapter's catch-all to NestJS 11 wildcard syntax; the conversion succeeds. It is
+  not the cause of a 404.
+- **Requests to the server root 404** — correct once a prefix is set. `POST /threads` is not served
+  when the prefix is `api`; use `/api/threads`.
+- **`GET /api` itself 404s** — expected, and not a sign the mount is wrong. Nest does not route the
+  bare prefix root to middleware ([nestjs/nest#14520](https://github.com/nestjs/nest/issues/14520)).
+  No protocol route lives there; probe `/api/assistants/search` instead.
+- **`/info` 404s** — also correct. It isn't part of the Agent Protocol surface skein serves; the
+  endpoints are `/threads`, `/assistants`, `/runs` and `/store/items`. Note `GET /ok` is only mounted
+  by the standalone `createNestServer` — `SkeinModule` adds no health route to your app.
+- **Everything 404s and you're on an older release** — the protocol ignored `setGlobalPrefix` before
+  this was fixed, so every path 404'd under a prefixed app. Upgrade, or drop the prefix and mount your
+  own controllers at `@Controller("api/…")` instead.
+
+### No `langgraph.json`? Pass a graph you already have
+
+`{ deps }` is the alternative to `{ config }`: bring a compiled graph straight from your code — no
+config file, no CLI. [`embedInMemoryGraphs`](../server-kit) turns a graph map into the
+`ProtocolDeps` the module needs:
+
+```ts
+import { Module } from "@nestjs/common";
+import { SkeinModule } from "@skein-js/nestjs";
+import { embedInMemoryGraphs } from "@skein-js/server-kit";
+
+import { agent } from "./graphs/agent-graph";
+
+@Module({
+  imports: [SkeinModule.forRoot({ deps: embedInMemoryGraphs({ agent }) })],
+  controllers: [/* your own controllers */],
+})
+export class AppModule {}
+```
+
+Map keys become graph ids. For durable state, swap in `embedPostgresGraphs` (Postgres + Redis) from
+[`@skein-js/runtime`](../runtime) — or, if you _do_ have a `langgraph.json` and just want production
+drivers, its `buildRuntime`. Full walkthrough: [docs/embedding.md](../../docs/embedding.md).
+
+## Graphs as plain endpoints (non-chat)
+
+For workloads that aren't chat — a classifier, an extractor, a workflow another service calls — there
+is a smaller surface: every graph mounted as `POST /invoke/:graph_id`, where the request body **is**
+the graph input and the response **is** the final state. No threads, assistants, or runs.
+
+```ts
+import { SkeinInvokeModule } from "@skein-js/nestjs";
+
+@Module({ imports: [SkeinInvokeModule.forRoot({ deps })] })
+export class AppModule {}
+```
+
+Send `Accept: text/event-stream` to stream the steps instead. See
+[docs/serving-a-single-graph.md](../../docs/serving-a-single-graph.md).
 
 ## Standalone server
 
@@ -48,6 +128,9 @@ await server.listen(2024);
 // on shutdown: await server.close();  // stops the run worker
 ```
 
+The same `{ deps }` seam applies here — `createNestServer({ deps: embedInMemoryGraphs({ agent }) })`
+serves a graph you hold in code, with no `langgraph.json` on disk.
+
 ## Streaming
 
 SSE responses write directly to the raw Node response and stream the pre-serialized frames the engine
@@ -64,16 +147,23 @@ produced, tearing the run's subscription down on client disconnect.
 - **`SKEIN_RUNTIME` / `SKEIN_LOGGER` / `SKEIN_CORS`** — DI tokens; inject `SKEIN_RUNTIME` to reach the
   `ResolvedProtocolRuntime` from your own providers — its `.runtime` is the `ProtocolRuntime`
   (assistants, handlers, worker), plus `.cors`.
+- **`SkeinInvokeModule.forRoot(options): DynamicModule`** — the simplified serving surface:
+  `POST /invoke/:graph_id` per graph, body-in / final-state-out, for non-chat workloads. Options add
+  `prefix` (default `/invoke`) and `streamMode`. Also exports `SkeinInvokeMiddleware` and the
+  `SKEIN_INVOKE` token.
 - **`SkeinRuntimeOptions`** — the shared seam every adapter accepts: common `{ logger?, cors?, warm? }`
   **plus** either `{ config, importModule? }` (in-memory runtime from a `langgraph.json`) **or**
-  `{ deps }` (bring-your-own `ProtocolDeps`, e.g. from [`@skein-js/runtime`](../runtime)'s
-  `buildRuntime`).
+  `{ deps }` (bring-your-own `ProtocolDeps`). Build `deps` in code with `embedInMemoryGraphs`
+  ([`@skein-js/server-kit`](../server-kit)) or `embedPostgresGraphs` ([`@skein-js/runtime`](../runtime)),
+  or from a `langgraph.json` with that package's `buildRuntime`.
 - Low-level mappers: `toProtocolRequest`, plus `sendNodeResponse` / `sendNodeError` (re-exported from
   [`@skein-js/server-kit`](../server-kit)).
 
 ## Learn more
 
 - [`@skein-js/express`](../server-express) — the reference adapter
+- [Embedding a graph you already have](../../docs/embedding.md) — the `{ deps }` path, no `langgraph.json`
+- [Serving a graph as a plain endpoint](../../docs/serving-a-single-graph.md) — the non-chat surface
 - [Building your own adapter](../../docs/building-an-adapter.md) · [skein-js overview](../../docs/index.md)
 
 ## License

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { NestModule, DynamicModule, MiddlewareConsumer, NestMiddleware, INestApplication } from '@nestjs/common';
-import { Logger, ProtocolRuntime, ProtocolRequest } from '@skein-js/agent-protocol';
+import { Logger, GraphInvokeOptions, ProtocolHandler, RouteMatcher, GraphInvokeHandlerName, ProtocolRuntime, ProtocolRequest } from '@skein-js/agent-protocol';
 import { SkeinRuntimeOptions, ResolvedProtocolRuntime, CorsSetting } from '@skein-js/server-kit';
 export { SkeinRuntimeOptions, sendNodeError, sendNodeResponse } from '@skein-js/server-kit';
 import { IncomingMessage, ServerResponse, IncomingHttpHeaders } from 'node:http';
+import { ApplicationConfig } from '@nestjs/core';
 
 declare class SkeinModule implements NestModule {
     /**
@@ -19,16 +20,18 @@ declare class SkeinModule implements NestModule {
     configure(consumer: MiddlewareConsumer): void;
 }
 
-/** The Node request the middleware reads (Express request is structurally compatible). */
+/** The Node request the middlewares read (an Express request is structurally compatible). */
 type NestRequest = IncomingMessage & {
     originalUrl?: string;
     body?: unknown;
 };
+
 declare class SkeinMiddleware implements NestMiddleware {
     private readonly resolved;
     private readonly logger;
     private readonly optionCors;
-    constructor(resolved: ResolvedProtocolRuntime, logger: Logger | null, optionCors: boolean | CorsSetting | null);
+    private readonly appConfig?;
+    constructor(resolved: ResolvedProtocolRuntime, logger: Logger | null, optionCors: boolean | CorsSetting | null, appConfig?: ApplicationConfig | undefined);
     use(req: NestRequest, res: ServerResponse, next: (error?: unknown) => void): Promise<void>;
 }
 
@@ -38,6 +41,38 @@ declare const SKEIN_RUNTIME: unique symbol;
 declare const SKEIN_LOGGER: unique symbol;
 /** Provides the explicit `cors` option (or `null`) so the middleware can apply CORS to skein routes. */
 declare const SKEIN_CORS: unique symbol;
+/** Provides the resolved single-graph invoke surface (handler + matcher) to `SkeinInvokeMiddleware`. */
+declare const SKEIN_INVOKE: unique symbol;
+
+type SkeinInvokeModuleOptions = SkeinRuntimeOptions & GraphInvokeOptions & {
+    /** Path prefix for the endpoint; defaults to `/invoke` (→ `POST /invoke/:graph_id`). */
+    prefix?: string;
+};
+declare class SkeinInvokeModule implements NestModule {
+    /**
+     * Serve the invoke surface from a `langgraph.json` (in-memory drivers) or an injected
+     * `ProtocolDeps`. Deps are resolved once, lazily, when the module initializes — no assistants are
+     * seeded and no background run worker is started, so there is nothing to shut down.
+     */
+    static forRoot(options: SkeinInvokeModuleOptions): DynamicModule;
+    configure(consumer: MiddlewareConsumer): void;
+}
+
+/** The resolved invoke surface the module provides: the handler plus its route matcher and CORS. */
+interface ResolvedInvokeSurface {
+    handler: ProtocolHandler;
+    match: RouteMatcher<GraphInvokeHandlerName>;
+    /** CORS derived from the config's `http.cors`, when the `{ config }` path was used. */
+    cors?: CorsSetting;
+}
+declare class SkeinInvokeMiddleware implements NestMiddleware {
+    private readonly invoke;
+    private readonly logger;
+    private readonly optionCors;
+    private readonly appConfig?;
+    constructor(invoke: ResolvedInvokeSurface, logger: Logger | null, optionCors: boolean | CorsSetting | null, appConfig?: ApplicationConfig | undefined);
+    use(req: NestRequest, res: ServerResponse, next: (error?: unknown) => void): Promise<void>;
+}
 
 interface SkeinNestServer {
     /** The Nest application, protocol mounted at `/`. */
@@ -64,4 +99,4 @@ interface NodeProtocolRequest {
 /** Translate a Node request (+ parsed URL, matched params, and already-parsed body) into a `ProtocolRequest`. */
 declare function toProtocolRequest(req: NodeProtocolRequest, url: URL, params: Record<string, string>, body: unknown): ProtocolRequest;
 
-export { SKEIN_CORS, SKEIN_LOGGER, SKEIN_RUNTIME, SkeinMiddleware, SkeinModule, type SkeinNestServer, createNestServer, toProtocolRequest };
+export { type ResolvedInvokeSurface, SKEIN_CORS, SKEIN_INVOKE, SKEIN_LOGGER, SKEIN_RUNTIME, SkeinInvokeMiddleware, SkeinInvokeModule, type SkeinInvokeModuleOptions, SkeinMiddleware, SkeinModule, type SkeinNestServer, createNestServer, toProtocolRequest };

package/dist/index.js

@@ -22,16 +22,35 @@ import {
 } from "@skein-js/server-kit";
 
 // src/skein.middleware.ts
-import { Inject, Injectable } from "@nestjs/common";
+import { Inject, Injectable, Optional } from "@nestjs/common";
+import { ApplicationConfig } from "@nestjs/core";
 import { copyThreadIdIntoBody, matchSkeinRoute } from "@skein-js/agent-protocol";
-import { SkeinHttpError } from "@skein-js/core";
 import {
   applyNodeCors,
   sendNodeError,
   sendNodePreflight,
-  sendNodeResponse
+  sendNodeResponse,
+  stripBasePath
 } from "@skein-js/server-kit";
 
+// src/read-json-body.ts
+import { SkeinHttpError } from "@skein-js/core";
+async function readJsonBody(req) {
+  if (req.body !== void 0) return req.body;
+  const contentType = req.headers["content-type"];
+  const single = Array.isArray(contentType) ? contentType[0] : contentType;
+  if (!single || !single.includes("application/json")) return void 0;
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  const text = Buffer.concat(chunks).toString("utf8");
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw SkeinHttpError.badRequest("Request body is not valid JSON.");
+  }
+}
+
 // src/to-protocol-request.ts
 function toSingleValueHeaders(headers) {
   const flattened = {};
@@ -63,34 +82,23 @@ function toProtocolRequest(req, url, params, body) {
 var SKEIN_RUNTIME = /* @__PURE__ */ Symbol("skein:runtime");
 var SKEIN_LOGGER = /* @__PURE__ */ Symbol("skein:logger");
 var SKEIN_CORS = /* @__PURE__ */ Symbol("skein:cors");
+var SKEIN_INVOKE = /* @__PURE__ */ Symbol("skein:invoke");
 
 // src/skein.middleware.ts
 function firstHeader(value) {
   return Array.isArray(value) ? value[0] : value;
 }
-async function readJsonBody(req) {
-  if (req.body !== void 0) return req.body;
-  const contentType = firstHeader(req.headers["content-type"]);
-  if (!contentType || !contentType.includes("application/json")) return void 0;
-  const chunks = [];
-  for await (const chunk of req) chunks.push(chunk);
-  const text = Buffer.concat(chunks).toString("utf8");
-  if (!text) return {};
-  try {
-    return JSON.parse(text);
-  } catch {
-    throw SkeinHttpError.badRequest("Request body is not valid JSON.");
-  }
-}
 var SkeinMiddleware = class {
-  constructor(resolved, logger, optionCors) {
+  constructor(resolved, logger, optionCors, appConfig) {
     this.resolved = resolved;
     this.logger = logger;
     this.optionCors = optionCors;
+    this.appConfig = appConfig;
   }
   resolved;
   logger;
   optionCors;
+  appConfig;
   async use(req, res, next) {
     const rawUrl = req.originalUrl ?? req.url ?? "/";
     const host = req.headers.host ?? "localhost";
@@ -101,18 +109,23 @@ var SkeinMiddleware = class {
       next();
       return;
     }
+    const skeinPathname = stripBasePath(url.pathname, this.appConfig?.getGlobalPrefix() ?? "");
+    if (skeinPathname === null) {
+      next();
+      return;
+    }
     const cors = this.optionCors ?? this.resolved.cors;
     const method = (req.method ?? "GET").toUpperCase();
     if (method === "OPTIONS") {
       const requestedMethod = firstHeader(req.headers["access-control-request-method"]);
-      if (cors && requestedMethod && matchSkeinRoute(requestedMethod, url.pathname)) {
+      if (cors && requestedMethod && matchSkeinRoute(requestedMethod, skeinPathname)) {
         sendNodePreflight(req.headers, res, cors);
         return;
       }
       next();
       return;
     }
-    const match = matchSkeinRoute(method, url.pathname);
+    const match = matchSkeinRoute(method, skeinPathname);
     if (!match) {
       next();
       return;
@@ -135,7 +148,9 @@ SkeinMiddleware = __decorateClass([
   Injectable(),
   __decorateParam(0, Inject(SKEIN_RUNTIME)),
   __decorateParam(1, Inject(SKEIN_LOGGER)),
-  __decorateParam(2, Inject(SKEIN_CORS))
+  __decorateParam(2, Inject(SKEIN_CORS)),
+  __decorateParam(3, Optional()),
+  __decorateParam(3, Inject(ApplicationConfig))
 ], SkeinMiddleware);
 
 // src/skein.module.ts
@@ -192,8 +207,135 @@ SkeinModule = __decorateClass([
   Module({})
 ], SkeinModule);
 
+// src/skein-invoke.module.ts
+import {
+  Module as Module2,
+  RequestMethod as RequestMethod2
+} from "@nestjs/common";
+import {
+  createGraphInvokeHandler,
+  createRouteMatcher,
+  graphInvokeRoutes
+} from "@skein-js/agent-protocol";
+import {
+  resolveRuntimeDeps
+} from "@skein-js/server-kit";
+
+// src/skein-invoke.middleware.ts
+import { Inject as Inject3, Injectable as Injectable3, Optional as Optional2 } from "@nestjs/common";
+import { ApplicationConfig as ApplicationConfig2 } from "@nestjs/core";
+import {
+  applyNodeCors as applyNodeCors2,
+  sendNodeError as sendNodeError2,
+  sendNodePreflight as sendNodePreflight2,
+  sendNodeResponse as sendNodeResponse2,
+  stripBasePath as stripBasePath2
+} from "@skein-js/server-kit";
+var SkeinInvokeMiddleware = class {
+  constructor(invoke, logger, optionCors, appConfig) {
+    this.invoke = invoke;
+    this.logger = logger;
+    this.optionCors = optionCors;
+    this.appConfig = appConfig;
+  }
+  invoke;
+  logger;
+  optionCors;
+  appConfig;
+  async use(req, res, next) {
+    const rawUrl = req.originalUrl ?? req.url ?? "/";
+    const host = req.headers.host ?? "localhost";
+    let url;
+    try {
+      url = new URL(rawUrl, `http://${host}`);
+    } catch {
+      next();
+      return;
+    }
+    const skeinPathname = stripBasePath2(url.pathname, this.appConfig?.getGlobalPrefix() ?? "");
+    if (skeinPathname === null) {
+      next();
+      return;
+    }
+    const cors = this.optionCors ?? this.invoke.cors;
+    const method = (req.method ?? "GET").toUpperCase();
+    if (method === "OPTIONS") {
+      const requested = Array.isArray(req.headers["access-control-request-method"]) ? req.headers["access-control-request-method"][0] : req.headers["access-control-request-method"];
+      if (cors && requested && this.invoke.match(requested, skeinPathname)) {
+        sendNodePreflight2(req.headers, res, cors);
+        return;
+      }
+      next();
+      return;
+    }
+    const match = this.invoke.match(method, skeinPathname);
+    if (!match) {
+      next();
+      return;
+    }
+    if (cors) applyNodeCors2(req.headers, res, cors);
+    const disconnected = new AbortController();
+    res.once("close", () => disconnected.abort(new Error("client disconnected")));
+    try {
+      const body = await readJsonBody(req);
+      const request = {
+        ...toProtocolRequest(req, url, match.params, body),
+        signal: disconnected.signal
+      };
+      await sendNodeResponse2(await this.invoke.handler(request), res);
+    } catch (error) {
+      sendNodeError2(error, res, this.logger ?? void 0, "skein NestJS invoke");
+    }
+  }
+};
+SkeinInvokeMiddleware = __decorateClass([
+  Injectable3(),
+  __decorateParam(0, Inject3(SKEIN_INVOKE)),
+  __decorateParam(1, Inject3(SKEIN_LOGGER)),
+  __decorateParam(2, Inject3(SKEIN_CORS)),
+  __decorateParam(3, Optional2()),
+  __decorateParam(3, Inject3(ApplicationConfig2))
+], SkeinInvokeMiddleware);
+
+// src/skein-invoke.module.ts
+var SkeinInvokeModule = class {
+  /**
+   * Serve the invoke surface from a `langgraph.json` (in-memory drivers) or an injected
+   * `ProtocolDeps`. Deps are resolved once, lazily, when the module initializes — no assistants are
+   * seeded and no background run worker is started, so there is nothing to shut down.
+   */
+  static forRoot(options) {
+    return {
+      module: SkeinInvokeModule,
+      providers: [
+        {
+          provide: SKEIN_INVOKE,
+          useFactory: async () => {
+            const { deps, cors } = await resolveRuntimeDeps(options);
+            return {
+              handler: createGraphInvokeHandler(deps, { streamMode: options.streamMode }),
+              match: createRouteMatcher(graphInvokeRoutes(options.prefix)),
+              cors
+            };
+          }
+        },
+        { provide: SKEIN_LOGGER, useValue: options.logger ?? null },
+        { provide: SKEIN_CORS, useValue: options.cors ?? null },
+        SkeinInvokeMiddleware
+      ],
+      exports: [SKEIN_INVOKE]
+    };
+  }
+  configure(consumer) {
+    consumer.apply(SkeinInvokeMiddleware).forRoutes({ path: "*", method: RequestMethod2.ALL });
+  }
+};
+SkeinInvokeModule = __decorateClass([
+  Module2({})
+], SkeinInvokeModule);
+
 // src/create-nest-server.ts
-import { Controller, Get, Module as Module2 } from "@nestjs/common";
+import { Controller, Get, Module as Module3 } from "@nestjs/common";
 import { NestFactory } from "@nestjs/core";
 import { resolveProtocolRuntime as resolveProtocolRuntime2 } from "@skein-js/server-kit";
 var SkeinHealthController = class {
@@ -212,7 +354,7 @@ async function createNestServer(options) {
   let SkeinRootModule = class {
   };
   SkeinRootModule = __decorateClass([
-    Module2({
+    Module3({
       imports: [SkeinModule.forResolvedRuntime(resolved, options.logger, options.cors)],
       controllers: [SkeinHealthController]
     })
@@ -231,15 +373,18 @@ async function createNestServer(options) {
 }
 
 // src/index.ts
-import { sendNodeResponse as sendNodeResponse2, sendNodeError as sendNodeError2 } from "@skein-js/server-kit";
+import { sendNodeResponse as sendNodeResponse3, sendNodeError as sendNodeError3 } from "@skein-js/server-kit";
 export {
   SKEIN_CORS,
+  SKEIN_INVOKE,
   SKEIN_LOGGER,
   SKEIN_RUNTIME,
+  SkeinInvokeMiddleware,
+  SkeinInvokeModule,
   SkeinMiddleware,
   SkeinModule,
   createNestServer,
-  sendNodeError2 as sendNodeError,
-  sendNodeResponse2 as sendNodeResponse,
+  sendNodeError3 as sendNodeError,
+  sendNodeResponse3 as sendNodeResponse,
   toProtocolRequest
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/nestjs",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "NestJS adapter for skein-js — serve the Agent Protocol from a Nest module.",
   "license": "Apache-2.0",
   "author": "Maina Wycliffe <wmmaina7@gmail.com>",
@@ -40,9 +40,9 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@skein-js/agent-protocol": "0.7.0",
-    "@skein-js/core": "0.7.0",
-    "@skein-js/server-kit": "0.7.0"
+    "@skein-js/agent-protocol": "0.9.0",
+    "@skein-js/server-kit": "0.9.0",
+    "@skein-js/core": "0.9.0"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0",
@@ -58,7 +58,7 @@
     "@nestjs/platform-express": "^11.0.0",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.1",
-    "@skein-js/storage-memory": "0.7.0"
+    "@skein-js/storage-memory": "0.9.0"
   },
   "publishConfig": {
     "access": "public"