@skein-js/fastify 0.8.0 → 0.9.0

package/README.md

@@ -46,6 +46,22 @@ await app.listen({ port: 3000 });
 // the Agent Protocol is now served under /agent/*
 ```
 
+## 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 { skeinInvokePlugin } from "@skein-js/fastify";
+
+await app.register(skeinInvokePlugin, { prefix: "/agent", deps });
+// → POST /agent/invoke/:graph_id
+```
+
+Send `Accept: text/event-stream` to stream the steps instead. See
+[docs/serving-a-single-graph.md](../../docs/serving-a-single-graph.md).
+
 ## Streaming
 
 SSE responses take over the raw Node response (`reply.hijack()` + `reply.raw`) and stream the
@@ -56,6 +72,8 @@ pre-serialized frames the engine produced, tearing the run's subscription down o
 - **`createFastifyServer(options): Promise<SkeinFastifyServer>`** — a standalone server;
   `SkeinFastifyServer` = `{ app, runtime, listen(port?, host?), close() }`. `listen` defaults to port
   `2024`, host `"localhost"`; `close()` stops the run worker then the HTTP server.
+- **`skeinInvokePlugin`** — the simplified serving surface (`POST /invoke/:graph_id`, body-in /
+  final-state-out). Options add `invokePrefix` (default `/invoke`) and `streamMode`.
 - **`skeinPlugin`** — a Fastify plugin: `await app.register(skeinPlugin, { prefix, ...options })`
   mounts the protocol under `prefix`. Encapsulated, so skein's routes + CORS stay isolated from the
   host app. Options: `SkeinPluginOptions` (an alias of `SkeinRuntimeOptions`); `prefix` is Fastify's

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Server } from 'node:http';
-import { ProtocolRuntime, Logger, ProtocolHandlers, ProtocolRequest, ProtocolResponse } from '@skein-js/agent-protocol';
+import { ProtocolRuntime, Logger, ProtocolHandlers, GraphInvokeOptions, ProtocolRequest, ProtocolResponse } from '@skein-js/agent-protocol';
 export { skeinRoutes } from '@skein-js/agent-protocol';
 import { SkeinRuntimeOptions, CorsOptions } from '@skein-js/server-kit';
 export { SkeinRuntimeOptions } from '@skein-js/server-kit';
@@ -33,8 +33,7 @@ interface HandlerRoutesOptions {
 /**
  * Bind the Agent Protocol route table to a handler table on a Fastify instance — the pure shim. It
  * assembles no runtime and knows no storage driver, so a caller with custom `ProtocolDeps` can mount
- * it over any `ProtocolHandlers`. Registers CORS first (when enabled) so preflight `OPTIONS` and the
- * `Access-Control-Allow-*` headers cover every route, including the SSE streams.
+ * it over any `ProtocolHandlers`.
  */
 declare function registerSkeinHandlers(fastify: FastifyInstance, handlers: ProtocolHandlers, options?: HandlerRoutesOptions): Promise<void>;
 /**
@@ -49,6 +48,25 @@ declare function registerSkeinHandlers(fastify: FastifyInstance, handlers: Proto
  */
 declare const skeinPlugin: FastifyPluginAsync<SkeinPluginOptions>;
 
+type SkeinInvokePluginOptions = SkeinRuntimeOptions & GraphInvokeOptions & {
+    /**
+     * Path prefix *inside* this plugin, appended to any Fastify `prefix` it is registered under.
+     * Defaults to `/invoke`; pass `"/"` to serve `:graph_id` directly at the registration prefix.
+     */
+    invokePrefix?: string;
+};
+/**
+ * A Fastify plugin serving `POST <invokePrefix>/:graph_id`. Resolves deps from the shared
+ * `{ config } | { deps }` seam; seeds no assistants and starts no background run worker, since an
+ * invoke-only service needs neither.
+ *
+ * ```ts
+ * await app.register(skeinInvokePlugin, { prefix: "/api", deps });
+ * // → POST /api/invoke/:graph_id
+ * ```
+ */
+declare const skeinInvokePlugin: FastifyPluginAsync<SkeinInvokePluginOptions>;
+
 /** Translate a Fastify `FastifyRequest` into the normalized `ProtocolRequest` the handler table reads. */
 declare function toProtocolRequest(req: FastifyRequest): ProtocolRequest;
 
@@ -58,4 +76,4 @@ declare function sendProtocolResponse(response: ProtocolResponse, reply: Fastify
 /** Serialize a caught error onto `reply`, using the protocol status when the error carries one. */
 declare function sendErrorResponse(error: unknown, reply: FastifyReply, logger?: Logger): void;
 
-export { type HandlerRoutesOptions, type SkeinFastifyServer, type SkeinPluginOptions, createFastifyServer, registerSkeinHandlers, sendErrorResponse, sendProtocolResponse, skeinPlugin, toProtocolRequest };
+export { type HandlerRoutesOptions, type SkeinFastifyServer, type SkeinInvokePluginOptions, type SkeinPluginOptions, createFastifyServer, registerSkeinHandlers, sendErrorResponse, sendProtocolResponse, skeinInvokePlugin, skeinPlugin, toProtocolRequest };

package/dist/index.js

@@ -106,7 +106,7 @@ var HTTP_METHOD_TO_FASTIFY = {
   patch: "PATCH",
   delete: "DELETE"
 };
-async function registerSkeinHandlers(fastify, handlers, options = {}) {
+async function prepareSkeinContext(fastify, options = {}) {
   if (options.cors) {
     let fastifyCors;
     try {
@@ -121,7 +121,10 @@ async function registerSkeinHandlers(fastify, handlers, options = {}) {
       options.cors === true ? { origin: true } : options.cors
     );
   }
-  fastify.removeContentTypeParser("application/json");
+  try {
+    fastify.removeContentTypeParser("application/json");
+  } catch {
+  }
   fastify.addContentTypeParser("application/json", { parseAs: "string" }, (_req, body, done) => {
     const text = (typeof body === "string" ? body : body.toString()).trim();
     if (text === "") {
@@ -134,6 +137,9 @@ async function registerSkeinHandlers(fastify, handlers, options = {}) {
       done(error);
     }
   });
+}
+async function registerSkeinHandlers(fastify, handlers, options = {}) {
+  await prepareSkeinContext(fastify, options);
   for (const binding of skeinRoutes) {
     const invoke = handlers[binding.handler];
     fastify.route({
@@ -195,6 +201,39 @@ async function createFastifyServer(options) {
   };
 }
 
+// src/skein-invoke-plugin.ts
+import {
+  createGraphInvokeHandler,
+  graphInvokeRoutes
+} from "@skein-js/agent-protocol";
+import { resolveRuntimeDeps } from "@skein-js/server-kit";
+var skeinInvokePlugin = async (fastify, options) => {
+  const { deps, cors } = await resolveRuntimeDeps(options);
+  const invoke = createGraphInvokeHandler(deps, { streamMode: options.streamMode });
+  await prepareSkeinContext(fastify, {
+    logger: options.logger,
+    // Explicit option wins; otherwise fall back to the config's `http.cors`, else off.
+    cors: options.cors ?? cors ?? false
+  });
+  for (const binding of graphInvokeRoutes(options.invokePrefix)) {
+    fastify.route({
+      method: HTTP_METHOD_TO_FASTIFY[binding.method],
+      url: binding.path,
+      handler: async (req, reply) => {
+        const disconnected = new AbortController();
+        reply.raw.once("close", () => disconnected.abort(new Error("client disconnected")));
+        try {
+          const request = { ...toProtocolRequest(req), signal: disconnected.signal };
+          await sendProtocolResponse(await invoke(request), reply);
+        } catch (error) {
+          sendErrorResponse(error, reply, options.logger);
+        }
+        return reply;
+      }
+    });
+  }
+};
+
 // src/index.ts
 import { skeinRoutes as skeinRoutes2 } from "@skein-js/agent-protocol";
 export {
@@ -202,6 +241,7 @@ export {
   registerSkeinHandlers,
   sendErrorResponse,
   sendProtocolResponse,
+  skeinInvokePlugin,
   skeinPlugin,
   skeinRoutes2 as skeinRoutes,
   toProtocolRequest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/fastify",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Fastify adapter for skein-js — mount the Agent Protocol as a Fastify plugin.",
   "license": "Apache-2.0",
   "author": "Maina Wycliffe <wmmaina7@gmail.com>",
@@ -40,9 +40,9 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@skein-js/core": "0.8.0",
-    "@skein-js/agent-protocol": "0.8.0",
-    "@skein-js/server-kit": "0.8.0"
+    "@skein-js/agent-protocol": "0.9.0",
+    "@skein-js/server-kit": "0.9.0",
+    "@skein-js/core": "0.9.0"
   },
   "peerDependencies": {
     "@fastify/cors": ">=8.0.0",
@@ -59,7 +59,7 @@
     "@langchain/core": "^1.2.0",
     "@langchain/langgraph": "^1.4.0",
     "fastify": "^5.2.0",
-    "@skein-js/storage-memory": "0.8.0"
+    "@skein-js/storage-memory": "0.9.0"
   },
   "publishConfig": {
     "access": "public"