@skein-js/server-kit 0.21.0 → 0.23.0

package/README.md

@@ -10,7 +10,7 @@ Part of **[skein-js](https://github.com/skein-js/skein-js)** — the open-source
 
 This package is the common ground the framework adapters ([`@skein-js/express`](../server-express),
 [`@skein-js/fastify`](../server-fastify), [`@skein-js/nestjs`](../server-nestjs),
-[`@skein-js/nextjs`](../server-nextjs)) stand on — so no adapter has to depend on another (or on
+[`@skein-js/nextjs`](../server-nextjs), and [`@skein-js/fetch`](../server-fetch)) stand on — so no adapter has to depend on another (or on
 Express) just to reuse it. It holds the framework-agnostic pieces (runtime assembly, dev-state import,
 CORS, and the Node-`http` transport the Node-based adapters share); each adapter still writes only the
 thin request/response shim its framework needs over the [`@skein-js/agent-protocol`](../agent-protocol)
@@ -31,6 +31,11 @@ handler table.
   `describeSnapshot`, from the **`@skein-js/server-kit/dev` subpath**: read an existing
   `.langgraph_api/` directory and reconstruct skein's own `DevStateSnapshot`, so adopting skein carries
   all local state over losslessly.
+- **Native HTTP and graph UI** — `loadConfigHttpHandler` loads exported Fetch/Hono applications
+  from `http.app` and graph UI from `ui`/`ui_config`. A 404 falls through with the original request
+  body preserved. `withNativePath`, `readNativeNodeRequest`, and `sendNativeResponse` share mounting
+  and streaming behavior across adapters; production assets are compiled by `skein build`. See
+  [CLI compatibility](https://skein-js.github.io/skein-js/langgraph-cli-compat#graph-ui-and-custom-http-applications).
 - **CORS** — `corsFromHttpConfig` / `toCorsOptions` map a `langgraph.json` `http.cors` block to
   `cors`-style `CorsOptions`; `allowedOrigin` / `corsResponseHeaders` / `applyNodeCors` /
   `sendNodePreflight` derive CORS headers for the adapters without a CORS middleware of their own

package/dist/channels-runtime-5TESQBKO.js

@@ -0,0 +1,213 @@
+// src/channels-runtime.ts
+import { createAuthScopedStore, createProtocolServiceFromContext } from "@skein-js/agent-protocol";
+import { SkeinConfigError } from "@skein-js/config";
+import {
+  SkeinHttpError
+} from "@skein-js/core";
+async function resolveChannels(input) {
+  const names = Object.keys(input.channels);
+  if (names.length === 0) return void 0;
+  const channels = await importChannelsPackage(names);
+  const registry = channels.buildChannelRegistry({
+    channels: Object.fromEntries(
+      Object.entries(input.channels).map(([name, loaded]) => [
+        name,
+        {
+          module: loaded.module,
+          config: {
+            assistant: loaded.assistant,
+            ...loaded.allowedAssistants ? { allowedAssistants: loaded.allowedAssistants } : {},
+            ...loaded.publicUrl ? { publicUrl: loaded.publicUrl } : {}
+          }
+        }
+      ])
+    ),
+    graphIds: input.graphIds
+  });
+  const channelInventory = registry.names.map((routeName) => {
+    const registered = registry.get(routeName);
+    if (!registered) throw new Error(`Channel registry lost configured route "${routeName}".`);
+    return {
+      route_name: routeName,
+      assistant: registered.config.assistant,
+      allowed_assistants: [...registered.config.allowedAssistants ?? []],
+      channel_name: registered.channel.name,
+      delivery_supported: typeof registered.channel.deliver === "function"
+    };
+  });
+  return {
+    routes: [
+      { method: "get", path: "/channels", handler: "listChannels" },
+      ...channels.channelRouteBindings(registry.names)
+    ],
+    wrapDispatcher: (inner) => channels.wrapChannelDispatcher({
+      registry,
+      inner,
+      logger: input.deps.logger ?? console
+    }),
+    handlers: (context) => ({
+      listChannels: async () => ({
+        kind: "json",
+        status: 200,
+        body: { channels: channelInventory }
+      }),
+      handleInboundEvent: async (req) => {
+        const name = req.url.split("?")[0].split("/channels/")[1] ?? "";
+        const registered = registry.get(name);
+        if (!registered) throw SkeinHttpError.notFound(`No channel named "${name}".`);
+        return channels.handleInboundEvent(
+          registered,
+          {
+            method: req.method,
+            url: req.url,
+            headers: req.headers,
+            ...typeof req.body === "string" ? { text: req.body } : {}
+          },
+          buildPipelineDeps(context, [
+            registered.config.assistant,
+            ...registered.config.allowedAssistants ?? []
+          ])
+        );
+      }
+    })
+  };
+}
+function buildPipelineDeps(context, allowedAssistants) {
+  const deps = context.deps;
+  const service = () => createProtocolServiceFromContext(context);
+  let requestFilters;
+  let verifiedContext;
+  const scopedService = (authContext, admission) => {
+    if (!authContext && !requestFilters && !admission) return service();
+    const base = context;
+    return createProtocolServiceFromContext({
+      ...base,
+      ...admission && deps.store.admission ? { admission } : {},
+      ...authContext?.user ? { authUser: authContext.user } : {},
+      ...authContext?.scopes ? { authScopes: authContext.scopes } : {},
+      deps: requestFilters && deps.auth ? {
+        ...base.deps,
+        store: createAuthScopedStore(base.deps.store, deps.auth, requestFilters, "threads")
+      } : base.deps
+    });
+  };
+  return {
+    ...deps.store.idempotency ? {
+      idempotency: {
+        ...deps.store.idempotency,
+        claim: async (input) => {
+          const authorizeRecorded = async (record) => {
+            const run = record.run_id ? await deps.store.runs.get(record.run_id) : null;
+            if (run) {
+              const assistant = await deps.store.assistants.get(run.assistant_id);
+              if (!allowedAssistants.includes(run.assistant_id) && !(assistant && allowedAssistants.includes(assistant.graph_id)))
+                throw SkeinHttpError.forbidden(
+                  "Recorded assistant is outside the channel allowlist.",
+                  { code: "assistant_not_allowed" }
+                );
+            }
+            if (!deps.auth) return;
+            const threadId = run?.thread_id ?? record.thread_id;
+            const decision = await deps.auth.authorize({
+              resource: "threads",
+              action: "create_run",
+              context: verifiedContext,
+              value: {
+                ...threadId ? { thread_id: threadId } : {},
+                ...run ? { run_id: run.run_id, assistant_id: run.assistant_id } : {}
+              }
+            });
+            const store = decision.filters ? createAuthScopedStore(deps.store, deps.auth, decision.filters, "threads") : deps.store;
+            if (threadId && !await store.threads.get(threadId))
+              throw SkeinHttpError.notFound("Thread not found.");
+            if (record.run_id && !await store.runs.get(record.run_id))
+              throw SkeinHttpError.notFound("Run not found.");
+          };
+          const accepted = deps.store.admission ? await deps.store.idempotency.get(`admission ${input.scope}`, input.key) : null;
+          if (accepted && accepted.expires_at > input.now && accepted.fingerprint === input.fingerprint && accepted.run_id) {
+            await authorizeRecorded(accepted);
+            return {
+              claimed: false,
+              record: {
+                ...accepted,
+                scope: input.scope,
+                response: { status: 202, body: { run_id: accepted.run_id } }
+              }
+            };
+          }
+          const result = await deps.store.idempotency.claim(input);
+          if (!result.claimed && result.record.status === "done")
+            await authorizeRecorded(result.record);
+          return result;
+        }
+      }
+    } : {},
+    clock: () => deps.clock ? deps.clock() : /* @__PURE__ */ new Date(),
+    logger: deps.logger ?? console,
+    // Straight off the run event bus — the same stream `runs.joinStream` serves, without the HTTP
+    // connection per conversation that reaching it from outside would cost.
+    runFrames: { subscribe: (runId) => deps.bus.subscribe(runId) },
+    authorize: async (principal, authz, value) => {
+      if (!deps.auth) return void 0;
+      const context2 = {
+        user: {
+          ...principal.metadata ?? {},
+          identity: principal.identity,
+          display_name: principal.identity,
+          is_authenticated: true,
+          permissions: principal.permissions ?? []
+        },
+        scopes: principal.permissions ?? []
+      };
+      verifiedContext = context2;
+      const decision = await deps.auth.authorize({
+        resource: authz.resource,
+        action: authz.action,
+        value: value ?? {},
+        context: context2
+      });
+      requestFilters = decision.filters;
+      return context2;
+    },
+    ensureThread: async (threadId, metadata, authContext) => {
+      await scopedService(authContext).threads.create({
+        thread_id: threadId,
+        metadata,
+        ifExists: "do_nothing"
+      });
+    },
+    threadStatus: async (threadId) => {
+      const thread = await scopedService(void 0).threads.get(threadId).catch(() => null);
+      return thread?.status ?? null;
+    },
+    createRun: async (input) => {
+      const run = await scopedService(input.authContext, input.admission).runs.createBackground(
+        input.threadId,
+        {
+          assistant_id: input.assistantId,
+          ...input.input !== void 0 ? { input: input.input } : {},
+          ...input.command ? { command: input.command } : {},
+          ...input.ifThreadStatus ? { if_thread_status: [...input.ifThreadStatus] } : {},
+          ...input.multitaskStrategy ? { multitask_strategy: input.multitaskStrategy } : {},
+          ...input.metadata ? { metadata: input.metadata } : {},
+          ...input.webhook ? { webhook: input.webhook } : {},
+          stream_mode: [...input.streamMode]
+        }
+      );
+      return { runId: run.run_id };
+    }
+  };
+}
+async function importChannelsPackage(names) {
+  try {
+    return await import("@skein-js/channels");
+  } catch (cause) {
+    throw new SkeinConfigError(
+      `skein.channels configures ${names.join(", ")}, but @skein-js/channels is not installed. Add it as a dependency.`,
+      { cause }
+    );
+  }
+}
+export {
+  resolveChannels
+};

package/dist/{chunk-UJZBVPYI.js → chunk-3IKRBGJU.js}

@@ -12,6 +12,286 @@ import {
 } from "@skein-js/config";
 import { MemorySkeinStore as MemorySkeinStore2 } from "@skein-js/storage-memory";
 
+// src/config-http-handler.ts
+import { pathToFileURL } from "url";
+import {
+  parseGraphSpec,
+  SkeinConfigError
+} from "@skein-js/config";
+
+// src/graph-ui.ts
+import { readFile } from "fs/promises";
+import path from "path";
+import { SkeinHttpError as SkeinHttpError2 } from "@skein-js/core";
+
+// src/native-http.ts
+import { serializeWireJson, SkeinHttpError } from "@skein-js/core";
+var sourceUrls = /* @__PURE__ */ new WeakMap();
+function withNativePath(request, pathname) {
+  const url = new URL(request.url);
+  url.pathname = pathname;
+  const native = new Request(url, request.clone());
+  sourceUrls.set(native, sourceUrls.get(request) ?? request.url);
+  return native;
+}
+function originalNativeUrl(request) {
+  return sourceUrls.get(request) ?? request.url;
+}
+function toNativeRequest(request, rawBody) {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(request.headers))
+    if (value !== void 0) headers.set(name, value);
+  const hasBody = !["GET", "HEAD"].includes(request.method.toUpperCase());
+  const body = !hasBody ? void 0 : rawBody ?? (request.body === void 0 ? void 0 : typeof request.body === "string" || request.body instanceof Uint8Array ? request.body : serializeWireJson(request.body));
+  if (!rawBody) headers.delete("content-length");
+  return new Request(request.url, {
+    method: request.method,
+    headers,
+    body: body instanceof Uint8Array ? new Uint8Array(body) : body,
+    signal: request.signal
+  });
+}
+async function readNativeNodeRequest(request, url, signal, handler) {
+  const matcher = handler?.[/* @__PURE__ */ Symbol.for("@skein-js/native-request-matcher")];
+  if (matcher?.(request.method ?? "GET", url) === false) return void 0;
+  const headers = {};
+  for (const [name, value] of Object.entries(request.headers))
+    headers[name] = Array.isArray(value) ? value.join(", ") : value;
+  let rawBody = request.rawBody;
+  if (!rawBody && request.body === void 0 && !["GET", "HEAD"].includes(request.method ?? "GET") && !request.readableEnded) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+      const bytes = chunk instanceof Uint8Array ? chunk : Buffer.from(String(chunk));
+      size += bytes.byteLength;
+      if (size > 100 * 1024)
+        throw SkeinHttpError.payloadTooLarge("Request body exceeds 102400 bytes.");
+      chunks.push(bytes);
+    }
+    rawBody = Buffer.concat(chunks);
+    request.rawBody = rawBody;
+    const text = new TextDecoder().decode(rawBody);
+    try {
+      request.body = headers["content-type"]?.includes("application/json") ? text ? JSON.parse(text) : {} : text;
+    } catch {
+      throw SkeinHttpError.badRequest("Request body is not valid JSON.");
+    }
+  }
+  const native = toNativeRequest(
+    { method: request.method ?? "GET", url, headers, body: request.body, signal },
+    rawBody
+  );
+  sourceUrls.set(native, new URL(request.originalUrl ?? request.url ?? url, url).href);
+  return native;
+}
+async function sendNativeResponse(response, target) {
+  target.statusCode = response.status;
+  for (const [name, value] of response.headers)
+    if (name !== "set-cookie") target.setHeader(name, value);
+  const cookies = response.headers.getSetCookie();
+  if (cookies.length) target.setHeader("set-cookie", cookies);
+  if (!response.body) {
+    target.end();
+    return;
+  }
+  const reader = response.body.getReader();
+  const close = () => {
+    void reader.cancel().catch(() => void 0);
+  };
+  target.once("close", close);
+  try {
+    for (; ; ) {
+      const chunk = await reader.read();
+      if (chunk.done || target.destroyed) break;
+      if (!target.write(chunk.value))
+        await new Promise((resolve) => {
+          const done = () => {
+            target.removeListener("drain", done);
+            target.removeListener("close", done);
+            resolve();
+          };
+          target.once("drain", done);
+          target.once("close", done);
+        });
+    }
+  } finally {
+    target.removeListener("close", close);
+    reader.releaseLock();
+    if (!target.writableEnded) target.end();
+  }
+}
+
+// src/graph-ui.ts
+var watches = /* @__PURE__ */ new Map();
+function escapeAttribute(value) {
+  return value.replace(
+    /[&<>"']/g,
+    (character) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[character]
+  );
+}
+async function readCompiledUi(config, configDir) {
+  const root = path.join(configDir, "ui");
+  let manifest;
+  try {
+    manifest = JSON.parse(
+      await readFile(path.join(root, "schemas.json"), "utf8")
+    );
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+  const files = /* @__PURE__ */ new Map();
+  for (const graphId of Object.keys(config.ui ?? {})) {
+    const assets = manifest[graphId]?.assets;
+    if (!Array.isArray(assets) || !assets.length)
+      throw new Error(`Built UI manifest has no assets for "${graphId}".`);
+    const loaded = [];
+    for (const basename of assets) {
+      if (typeof basename !== "string" || basename !== path.basename(basename) || basename === "." || basename === "..")
+        throw new Error("Built UI manifest contains an invalid asset name.");
+      const filename = path.resolve(root, "public", graphId, basename);
+      if (!filename.startsWith(`${path.resolve(root, "public")}${path.sep}`))
+        throw new Error("Built UI asset escapes its artifact directory.");
+      loaded.push({ basename, contents: new Uint8Array(await readFile(filename)) });
+    }
+    files.set(graphId, loaded);
+  }
+  return files;
+}
+async function loadGraphUiHandler(config, configDir) {
+  if (!config.ui || !Object.keys(config.ui).length) return void 0;
+  let files = await readCompiledUi(config, configDir);
+  if (!files) {
+    const key = JSON.stringify([configDir, config.ui, config.ui_config]);
+    let pending = watches.get(key);
+    if (!pending) {
+      pending = (async () => {
+        const { build, watch } = await import(
+          /* webpackIgnore: true */
+          "@langchain/langgraph-ui"
+        );
+        await build({
+          cwd: configDir,
+          defs: config.ui,
+          config: config.ui_config,
+          output: ".skein/ui"
+        });
+        const results = await readCompiledUi(config, path.join(configDir, ".skein"));
+        await watch({
+          cwd: configDir,
+          defs: config.ui,
+          config: config.ui_config,
+          onOutput: (graphId, output) => {
+            results.set(graphId, output);
+          }
+        });
+        return results;
+      })();
+      watches.set(key, pending);
+      void pending.catch(() => watches.delete(key));
+    }
+    files = await pending;
+  }
+  const registry = files;
+  return async (request) => {
+    const url = new URL(request.url);
+    const match = /^\/ui\/([^/]+)(?:\/([^/]+))?$/.exec(url.pathname);
+    if (!match) return void 0;
+    let graphId;
+    let basename;
+    try {
+      graphId = decodeURIComponent(match[1]);
+      basename = match[2] ? decodeURIComponent(match[2]) : void 0;
+    } catch {
+      throw SkeinHttpError2.badRequest("Invalid UI path encoding.");
+    }
+    const assets = registry.get(graphId);
+    if (!assets?.length) return new Response("UI not found", { status: 404 });
+    if (request.method === "GET" && basename) {
+      const asset = assets.find((file) => file.basename === basename);
+      if (!asset) return new Response("Asset not found", { status: 404 });
+      const mime = {
+        ".js": "text/javascript",
+        ".css": "text/css",
+        ".json": "application/json",
+        ".svg": "image/svg+xml",
+        ".png": "image/png",
+        ".woff2": "font/woff2"
+      };
+      return new Response(new Uint8Array(asset.contents), {
+        headers: {
+          "content-type": mime[path.extname(basename)] ?? "application/octet-stream",
+          "cache-control": "no-cache"
+        }
+      });
+    }
+    if (request.method !== "POST" || basename) return void 0;
+    let body;
+    try {
+      body = await request.json();
+    } catch {
+      throw SkeinHttpError2.badRequest("UI bootstrap requires JSON.");
+    }
+    if (typeof body !== "object" || body === null || !("name" in body) || typeof body.name !== "string")
+      throw SkeinHttpError2.badRequest("UI bootstrap requires a component name.");
+    const assetUrl = (basename2) => escapeAttribute(
+      new URL(
+        `${encodeURIComponent(graphId)}/${encodeURIComponent(basename2)}`,
+        originalNativeUrl(request)
+      ).href
+    );
+    const html = assets.filter((file) => file.basename.endsWith(".css")).map((file) => `<link rel="stylesheet" href="${assetUrl(file.basename)}" />`);
+    const script = assets.find((file) => file.basename.endsWith(".js"));
+    if (script) {
+      const stableName = graphId.replace(/[^a-zA-Z0-9]/g, "_");
+      const render = `__LGUI_${stableName}.render(${JSON.stringify(body.name)}, "{{shadowRootId}}")`;
+      html.push(
+        `<script src="${assetUrl(script.basename)}" onload="${escapeAttribute(render)}"></script>`
+      );
+    }
+    return new Response(html.join("\n"), {
+      headers: { "content-type": "text/html; charset=utf-8" }
+    });
+  };
+}
+
+// src/config-http-handler.ts
+async function loadConfigHttpHandler(config, options) {
+  const app = config.http?.["app"];
+  const ui = await loadGraphUiHandler(config, options.configDir);
+  if (app === void 0) return ui;
+  if (typeof app !== "string") throw new SkeinConfigError("http.app must be a path:export string.");
+  const spec = parseGraphSpec(app, options.configDir);
+  const importer = options.importModule ?? ((file) => import(pathToFileURL(file).href));
+  const module = await importer(spec.sourceFile);
+  const exported = module[spec.exportSymbol];
+  let fetch;
+  if (typeof exported === "function") fetch = exported;
+  else if (typeof exported === "object" && exported !== null && "fetch" in exported && typeof exported.fetch === "function")
+    fetch = exported.fetch.bind(exported);
+  else
+    throw new SkeinConfigError(
+      `http.app "${app}" must export a Fetch function or an object with fetch().`
+    );
+  return async (request) => {
+    const applicationRequest = request.clone();
+    let response;
+    try {
+      response = await fetch(applicationRequest);
+      if (!(response instanceof Response)) throw new TypeError("http.app must return a Response.");
+      if (response.status === 404) {
+        void response.body?.cancel().catch(() => void 0);
+        return ui?.(request);
+      }
+      void request.body?.cancel().catch(() => void 0);
+      return response;
+    } finally {
+      if (!response || response.status === 404 || response.body !== applicationRequest.body)
+        void applicationRequest.body?.cancel().catch(() => void 0);
+    }
+  };
+}
+
 // src/cors-config.ts
 import {
   filterSkeinRoutes,
@@ -53,6 +333,8 @@ function corsFromHttpConfig(http) {
   return toCorsOptions(cors);
 }
 var DISABLE_FLAGS = {
+  disable_mcp: "mcp",
+  disable_a2a: "a2a",
   disable_assistants: "assistants",
   disable_threads: "threads",
   disable_runs: "runs",
@@ -102,20 +384,26 @@ function resolveIdempotency(raw) {
 import { MemorySaver } from "@langchain/langgraph";
 import {
   cloneLangGraphCheckpoint,
+  inspectMemoryThreadStorage,
   normalizeEmbeddableGraphs,
   SkeinBaseStore
 } from "@skein-js/langgraph";
-import { MemoryRunEventBus, MemoryRunQueue, MemorySkeinStore } from "@skein-js/storage-memory";
+import {
+  MemoryRunEventBus,
+  MemoryThreadEventBus,
+  MemoryRunQueue,
+  MemorySkeinStore
+} from "@skein-js/storage-memory";
 
 // src/max-page-size.ts
 import { DEFAULT_MAX_PAGE_SIZE } from "@skein-js/core";
 
 // src/env-numbers.ts
-import { SkeinConfigError } from "@skein-js/config/errors";
+import { SkeinConfigError as SkeinConfigError2 } from "@skein-js/config/errors";
 function requirePositiveInteger(source, raw) {
   const parsed = Number(raw);
   if (!Number.isSafeInteger(parsed) || parsed <= 0) {
-    throw new SkeinConfigError(`${source} must be a positive integer (got "${String(raw)}").`);
+    throw new SkeinConfigError2(`${source} must be a positive integer (got "${String(raw)}").`);
   }
   return parsed;
 }
@@ -196,6 +484,7 @@ import {
 } from "@skein-js/langgraph";
 function embedInMemoryGraphs(graphs, overrides = {}) {
   const webhooks = resolveWebhooks(void 0);
+  const checkpointer = overrides.checkpointer ?? new MemorySaver();
   return {
     // `maxPageSize` resolved for the same reason as the bus limits below: an embedded host's
     // `SKEIN_MAX_PAGE_SIZE` has to reach the driver that applies it.
@@ -205,7 +494,11 @@ function embedInMemoryGraphs(graphs, overrides = {}) {
     // Resolved rather than defaulted, so `SKEIN_MEMORY_BUS_*` reaches an embedded host too — this is
     // the driver set a long-lived single-process deployment actually runs on.
     bus: new MemoryRunEventBus(resolveMemoryBusLimits()),
-    checkpointer: new MemorySaver(),
+    threadBus: new MemoryThreadEventBus(),
+    checkpointer,
+    ...checkpointer instanceof MemorySaver ? {
+      inspectThreadStorage: (threadId) => inspectMemoryThreadStorage(checkpointer, threadId)
+    } : {},
     // Bridges long-term memory into a LangGraph `BaseStore` so nodes reach it via `getStore()`. A
     // function on deps rather than an import inside the engine — see `ProtocolDeps.storeBridge`.
     storeBridge: (store) => new SkeinBaseStore(store),
@@ -229,6 +522,7 @@ var createInMemoryDeps = embedInMemoryGraphs;
 function resolveThreadTtl(raw) {
   if (!raw) return void 0;
   const ttl = {};
+  if (raw.strategy === "keep_latest") ttl.strategy = raw.strategy;
   if (typeof raw.default_ttl === "number") ttl.defaultTtl = raw.default_ttl;
   if (typeof raw.sweep_interval_minutes === "number") {
     ttl.sweepIntervalMinutes = raw.sweep_interval_minutes;
@@ -262,6 +556,7 @@ async function loadInMemoryRuntime(configPath, importModule, staticSchemas) {
   });
   const deps = embedInMemoryGraphs(toGraphResolver(graphs));
   deps.auth = await loadAuthEngine(config.auth, { configDir, importModule });
+  deps.httpHandler = await loadConfigHttpHandler(config, { configDir, importModule });
   return {
     deps,
     channels: await loadChannels(config.skein?.channels, {
@@ -296,6 +591,10 @@ async function loadReloadableInMemoryRuntime(configPath, importModule, staticSch
     store,
     checkpointer,
     auth: await loadAuthEngine(first.config.auth, { configDir: first.configDir, importModule }),
+    httpHandler: await loadConfigHttpHandler(first.config, {
+      configDir: first.configDir,
+      importModule
+    }),
     // Present only when configured — its presence is what starts the thread TTL sweeper.
     ...threadTtl ? { threadTtl } : {},
     // Unlike `threadTtl`, absence here means *defaults*, not *off*: the header is honoured either way.
@@ -319,7 +618,13 @@ async function loadReloadableInMemoryRuntime(configPath, importModule, staticSch
     config: first.config,
     configDir: first.configDir,
     reloadGraphs: async () => {
-      current = (await loadConfig({ configPath, importModule, staticSchemas })).graphs;
+      const next = await loadConfig({ configPath, importModule, staticSchemas });
+      const httpHandler = await loadConfigHttpHandler(next.config, {
+        configDir: next.configDir,
+        importModule
+      });
+      current = next.graphs;
+      deps.httpHandler = httpHandler;
     },
     snapshotState: () => ({
       version: 1,
@@ -336,6 +641,11 @@ async function loadReloadableInMemoryRuntime(configPath, importModule, staticSch
 export {
   requirePositiveInteger,
   positiveIntegerFromEnv,
+  withNativePath,
+  toNativeRequest,
+  readNativeNodeRequest,
+  sendNativeResponse,
+  loadConfigHttpHandler,
   toCorsOptions,
   corsFromHttpConfig,
   disabledRoutesFromHttpConfig,

package/dist/{in-memory-runtime-IOQZUNLV.js → in-memory-runtime-D4PEZVMU.js}

@@ -1,7 +1,7 @@
 import {
   loadInMemoryRuntime,
   loadReloadableInMemoryRuntime
-} from "./chunk-UJZBVPYI.js";
+} from "./chunk-3IKRBGJU.js";
 import "./chunk-JUBBCC7R.js";
 export {
   loadInMemoryRuntime,

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ProtocolRuntime, RouteBinding, Logger, ProtocolDeps, RunWorkerOptions, CronSchedulerOptions, RunFailureReport, IdempotencyConfig, WebhookDeliveryConfig, GraphResolver, RouteMatcher, DisabledRouteGroups, ProtocolResponse } from '@skein-js/agent-protocol';
+import { ProtocolRuntime, RouteBinding, Logger, ProtocolDeps, RunWorkerOptions, CronSchedulerOptions, RunFailureReport, IdempotencyConfig, WebhookDeliveryConfig, GraphResolver, RouteMatcher, DisabledRouteGroups, ProtocolResponse, ProtocolRequest } from '@skein-js/agent-protocol';
 export { CompiledGraphFactory, DEFAULT_RUN_CONCURRENCY, DEFAULT_SHUTDOWN_GRACE_MS, GraphResolver, Logger, ProtocolDeps, ResolvedGraph, RunWorkerOptions } from '@skein-js/agent-protocol';
 import { LoadedChannel, ModuleImporter, LanggraphJson, GraphSchemas } from '@skein-js/config';
 import { CorsOptions } from 'cors';
@@ -9,9 +9,11 @@ export { a as DevStateCounts } from './dev-Zz4VRv7T.js';
 import { StoreTtlConfig, ThreadTtlConfig } from '@skein-js/core';
 import { EmbeddableGraph } from '@skein-js/langgraph';
 export { EmbeddableGraph, graphMapToResolver, normalizeEmbeddableGraphs } from '@skein-js/langgraph';
-import { ServerResponse } from 'node:http';
+import { ServerResponse, IncomingMessage } from 'node:http';
 
 interface SkeinRuntimeCommonOptions {
+    /** Override the mounted protocol route inventory, including discovery. */
+    routes?: readonly RouteBinding[];
     /**
      * Where skein reports itself: failed runs, webhook delivery failures, background-run summaries, and
      * the adapter's own transport faults. It reaches **the run engine**, not just the transport — this
@@ -469,15 +471,14 @@ extraDeps?: Partial<Omit<ProtocolDeps, "graphs">>): Promise<ReloadableInMemoryRu
 /** The raw `checkpointer.ttl` block as `langgraph.json` spells it. */
 interface RawThreadTtl {
     default_ttl?: number;
-    strategy?: "delete";
+    strategy?: "delete" | "keep_latest";
     sweep_interval_minutes?: number;
 }
 /**
  * Map the raw block to {@link ThreadTtlConfig}, or `undefined` when nothing is set — so threads never
  * expire unless asked to, and no sweeper is started.
  *
- * `strategy` is read only to be validated by the config schema: `"delete"` is the only thing an
- * expired thread can become, so there is nothing for the drivers to branch on.
+ * Deletion stays the default; keep_latest is explicit so existing deployments retain their policy.
  */
 declare function resolveThreadTtl(raw: RawThreadTtl | undefined): ThreadTtlConfig | undefined;
 /** The raw `store.ttl` block as `langgraph.json` spells it. */
@@ -716,4 +717,25 @@ type RuntimeGlobal = typeof globalThis & {
 /** Detect Node, Bun, or Deno without importing a runtime-specific module. */
 declare function detectRuntimeCapabilities(scope?: RuntimeGlobal): RuntimeCapabilities;
 
-export { type ConsoleLogLevel, type ConsoleLoggerOptions, type CorsSetting, DEFAULT_HEAP_SAMPLE_MS, DEFAULT_HEAP_WARN_PERCENT, DevStateSnapshot, type FileReader, HEAP_REARM_MARGIN_PERCENT, HEAP_REARM_PERCENT, type HeapHeadroom, type HeapPressureContext, type HeapPressureMonitor, type HeapPressureMonitorOptions, type InMemoryRuntimeConfig, type IntervalHandle, type LanggraphCorsConfig, type RawIdempotency, type RawStoreTtl, type RawThreadTtl, type RawWebhooks, type ReloadableInMemoryRuntime, type ResolvedMemoryBusLimits, type ResolvedProtocolRuntime, type ResolvedRuntimeDeps, type RuntimeCapabilities, type RuntimeMemorySnapshot, type RuntimeSignalSubscription, type SkeinRuntimeCommonOptions, type SkeinRuntimeOptions, allowedOrigin, applyNodeCors, checkHeapHeadroom, consoleMountFromHttpConfig, corsFromHttpConfig, corsPreflightHeaders, corsResponseHeaders, createConsoleLogger, createInMemoryDeps, describeError, describeHeapHeadroom, describePoolPressure, detectRuntimeCapabilities, disabledRoutesFromHttpConfig, embedInMemoryGraphs, formatLogMeta, joinList, loadInMemoryRuntime, loadReloadableInMemoryRuntime, readContainerMemoryLimit, resolveCronTickMs, resolveHeapPressureOptions, resolveIdempotency, resolveMaxPageSize, resolveMemoryBusLimits, resolveProtocolRuntime, resolveRunConcurrency, resolveRunTimeoutMs, resolveRuntimeDeps, resolveShutdownGraceMs, resolveStoreTtl, resolveThreadTtl, resolveWebhooks, routeMatcherFor, routesFromHttpConfig, runFailureIdentity, sendNodeError, sendNodePreflight, sendNodeResponse, startHeapPressureMonitor, stripBasePath, toCorsOptions };
+/** Load the same path:export notation as graphs; preserve Hono's receiver for its fetch method. */
+declare function loadConfigHttpHandler(config: LanggraphJson, options: {
+    configDir: string;
+    importModule?: ModuleImporter;
+}): Promise<((request: Request) => Promise<Response | undefined>) | undefined>;
+
+/** Strip a mount path for app dispatch while retaining the public URL for asset references. */
+declare function withNativePath(request: Request, pathname: string): Request;
+/** Build a Fetch request from a framework's normalized body without changing protocol responses. */
+declare function toNativeRequest(request: Pick<ProtocolRequest, "method" | "url" | "headers" | "body" | "signal">, rawBody?: Uint8Array): Request;
+/** Native Node bridge also handles binary/form bodies when the host has not parsed them. */
+type NativeNodeRequest = IncomingMessage & {
+    body?: unknown;
+    rawBody?: Uint8Array;
+    originalUrl?: string;
+};
+declare function readNativeNodeRequest(request: NativeNodeRequest, url: string, signal?: AbortSignal): Promise<Request>;
+declare function readNativeNodeRequest(request: NativeNodeRequest, url: string, signal: AbortSignal | undefined, handler: (request: Request) => Promise<Response | undefined>): Promise<Request | undefined>;
+/** Stream binary, HTML, JSON or SSE from a native app with backpressure and cancellation. */
+declare function sendNativeResponse(response: Response, target: ServerResponse): Promise<void>;
+
+export { type ConsoleLogLevel, type ConsoleLoggerOptions, type CorsSetting, DEFAULT_HEAP_SAMPLE_MS, DEFAULT_HEAP_WARN_PERCENT, DevStateSnapshot, type FileReader, HEAP_REARM_MARGIN_PERCENT, HEAP_REARM_PERCENT, type HeapHeadroom, type HeapPressureContext, type HeapPressureMonitor, type HeapPressureMonitorOptions, type InMemoryRuntimeConfig, type IntervalHandle, type LanggraphCorsConfig, type RawIdempotency, type RawStoreTtl, type RawThreadTtl, type RawWebhooks, type ReloadableInMemoryRuntime, type ResolvedMemoryBusLimits, type ResolvedProtocolRuntime, type ResolvedRuntimeDeps, type RuntimeCapabilities, type RuntimeMemorySnapshot, type RuntimeSignalSubscription, type SkeinRuntimeCommonOptions, type SkeinRuntimeOptions, allowedOrigin, applyNodeCors, checkHeapHeadroom, consoleMountFromHttpConfig, corsFromHttpConfig, corsPreflightHeaders, corsResponseHeaders, createConsoleLogger, createInMemoryDeps, describeError, describeHeapHeadroom, describePoolPressure, detectRuntimeCapabilities, disabledRoutesFromHttpConfig, embedInMemoryGraphs, formatLogMeta, joinList, loadConfigHttpHandler, loadInMemoryRuntime, loadReloadableInMemoryRuntime, readContainerMemoryLimit, readNativeNodeRequest, resolveCronTickMs, resolveHeapPressureOptions, resolveIdempotency, resolveMaxPageSize, resolveMemoryBusLimits, resolveProtocolRuntime, resolveRunConcurrency, resolveRunTimeoutMs, resolveRuntimeDeps, resolveShutdownGraceMs, resolveStoreTtl, resolveThreadTtl, resolveWebhooks, routeMatcherFor, routesFromHttpConfig, runFailureIdentity, sendNativeResponse, sendNodeError, sendNodePreflight, sendNodeResponse, startHeapPressureMonitor, stripBasePath, toCorsOptions, toNativeRequest, withNativePath };

package/dist/index.js

@@ -5,10 +5,12 @@ import {
   disabledRoutesFromHttpConfig,
   embedInMemoryGraphs,
   graphMapToResolver,
+  loadConfigHttpHandler,
   loadInMemoryRuntime,
   loadReloadableInMemoryRuntime,
   normalizeEmbeddableGraphs,
   positiveIntegerFromEnv,
+  readNativeNodeRequest,
   requirePositiveInteger,
   resolveIdempotency,
   resolveMaxPageSize,
@@ -17,8 +19,11 @@ import {
   resolveThreadTtl,
   resolveWebhooks,
   routesFromHttpConfig,
-  toCorsOptions
-} from "./chunk-UJZBVPYI.js";
+  sendNativeResponse,
+  toCorsOptions,
+  toNativeRequest,
+  withNativePath
+} from "./chunk-3IKRBGJU.js";
 import "./chunk-JUBBCC7R.js";
 
 // src/resolve-runtime.ts
@@ -168,13 +173,13 @@ function resolveLogger(option, injected, frameworkLogger) {
   return option ?? frameworkLogger;
 }
 async function resolveRuntimeDeps(options, frameworkLogger) {
-  const loaded = options.deps ? { deps: options.deps, cors: void 0, routes: skeinRoutes, channels: options.channels } : await (await import("./in-memory-runtime-IOQZUNLV.js")).loadInMemoryRuntime(options.config, options.importModule);
+  const loaded = options.deps ? { deps: options.deps, cors: void 0, routes: skeinRoutes, channels: options.channels } : await (await import("./in-memory-runtime-D4PEZVMU.js")).loadInMemoryRuntime(options.config, options.importModule);
   const logger = resolveLogger(options.logger, loaded.deps.logger, frameworkLogger);
   if (logger && !loaded.deps.logger) loaded.deps.logger = logger;
   return {
     deps: loaded.deps,
     cors: loaded.cors,
-    routes: loaded.routes,
+    routes: options.routes ?? loaded.routes,
     ...loaded.channels ? { channels: loaded.channels } : {},
     logger
   };
@@ -190,22 +195,18 @@ async function resolveProtocolRuntime(options, frameworkLogger) {
   const heapPressureOptions = resolveHeapPressureOptions();
   const runTimeoutMs = resolveRunTimeoutMs(deps.runTimeoutMs);
   if (runTimeoutMs !== void 0) deps.runTimeoutMs = runTimeoutMs;
-  const runtimeRef = {};
-  const channelSurface = channels ? await (await import("./channels-runtime-JHTMXARF.js")).resolveChannels({
+  const channelSurface = channels ? await (await import("./channels-runtime-5TESQBKO.js")).resolveChannels({
     channels,
     graphIds: deps.graphs.ids,
-    deps,
-    service: () => {
-      const current = runtimeRef.current;
-      if (!current) throw new Error("channel pipeline used before the runtime was assembled");
-      return current.service;
-    }
+    deps
   }) : void 0;
   if (channelSurface) {
     const inner = deps.webhookDispatcher ?? fetchWebhookDispatcher;
     deps.webhookDispatcher = channelSurface.wrapDispatcher(inner);
   }
+  const mountedRoutes = channelSurface ? [...routes, ...channelSurface.routes] : routes;
   const runtime = createProtocolRuntime(deps, {
+    routes: mountedRoutes,
     ...channelSurface ? { handlers: channelSurface.handlers } : {},
     worker: {
       ...options.worker,
@@ -220,7 +221,6 @@ async function resolveProtocolRuntime(options, frameworkLogger) {
       enabled: options.scheduler?.enabled ?? routes.some((route) => route.group === "crons")
     }
   });
-  runtimeRef.current = runtime;
   await runtime.service.assistants.registerGraphAssistants();
   if (options.warm) {
     await Promise.all(
@@ -262,7 +262,7 @@ async function resolveProtocolRuntime(options, frameworkLogger) {
     // Channel routes are *appended*, never declared in `skeinRoutes`: they exist only when a channel
     // is configured, which is what makes the feature undetectable to a deployment that never wanted
     // it — strictly stronger than an `http.disable_*` flag, and it needs no `RouteGroup` to express.
-    routes: channelSurface ? [...routes, ...channelSurface.routes] : routes,
+    routes: mountedRoutes,
     logger
   };
 }
@@ -707,10 +707,12 @@ export {
   formatLogMeta,
   graphMapToResolver,
   joinList,
+  loadConfigHttpHandler,
   loadInMemoryRuntime,
   loadReloadableInMemoryRuntime,
   normalizeEmbeddableGraphs,
   readContainerMemoryLimit,
+  readNativeNodeRequest,
   resolveCronTickMs,
   resolveHeapPressureOptions,
   resolveIdempotency,
@@ -727,10 +729,13 @@ export {
   routeMatcherFor,
   routesFromHttpConfig,
   runFailureIdentity,
+  sendNativeResponse,
   sendNodeError,
   sendNodePreflight,
   sendNodeResponse,
   startHeapPressureMonitor,
   stripBasePath,
-  toCorsOptions
+  toCorsOptions,
+  toNativeRequest,
+  withNativePath
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/server-kit",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Shared, framework-agnostic building blocks for skein-js HTTP adapters — in-memory dev runtime, LangGraph dev-state import, and langgraph.json CORS mapping.",
   "license": "Apache-2.0",
   "author": "Maina Wycliffe <wmmaina7@gmail.com>",
@@ -49,22 +49,23 @@
     "cors": "^2.8.5",
     "superjson": "^2.2.6",
     "zod": "^3.25.76",
-    "@skein-js/agent-protocol": "0.21.0",
-    "@skein-js/config": "0.21.0",
-    "@skein-js/core": "0.21.0",
-    "@skein-js/langgraph": "0.21.0",
-    "@skein-js/storage-memory": "0.21.0"
+    "@skein-js/agent-protocol": "0.23.0",
+    "@skein-js/core": "0.23.0",
+    "@skein-js/config": "0.23.0",
+    "@skein-js/langgraph": "0.23.0",
+    "@skein-js/storage-memory": "0.23.0"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0",
-    "@skein-js/channels": "0.21.0"
+    "@skein-js/channels": "0.23.0"
   },
   "devDependencies": {
     "@langchain/core": "^1.2.9",
     "@langchain/langgraph": "^1.4.0",
     "@langchain/langgraph-sdk": "^1.9.0",
     "@types/cors": "^2.8.17",
-    "@skein-js/channels": "0.21.0"
+    "hono": "4.13.13",
+    "@skein-js/channels": "0.23.0"
   },
   "publishConfig": {
     "access": "public"
@@ -73,5 +74,8 @@
     "@skein-js/channels": {
       "optional": true
     }
+  },
+  "optionalDependencies": {
+    "@langchain/langgraph-ui": "1.4.2"
   }
 }

package/dist/channels-runtime-JHTMXARF.js

@@ -1,156 +0,0 @@
-// src/channels-runtime.ts
-import {
-  createAuthScopedStore,
-  createContext,
-  createProtocolServiceFromContext
-} from "@skein-js/agent-protocol";
-import { SkeinConfigError } from "@skein-js/config";
-import { SkeinHttpError } from "@skein-js/core";
-async function resolveChannels(input) {
-  const names = Object.keys(input.channels);
-  if (names.length === 0) return void 0;
-  const channels = await importChannelsPackage(names);
-  const registry = channels.buildChannelRegistry({
-    channels: Object.fromEntries(
-      Object.entries(input.channels).map(([name, loaded]) => [
-        name,
-        {
-          module: loaded.module,
-          config: {
-            assistant: loaded.assistant,
-            ...loaded.allowedAssistants ? { allowedAssistants: loaded.allowedAssistants } : {},
-            ...loaded.publicUrl ? { publicUrl: loaded.publicUrl } : {}
-          }
-        }
-      ])
-    ),
-    graphIds: input.graphIds
-  });
-  const pipelineDeps = buildPipelineDeps(input.deps, input.service);
-  const channelInventory = registry.names.map((routeName) => {
-    const registered = registry.get(routeName);
-    if (!registered) throw new Error(`Channel registry lost configured route "${routeName}".`);
-    return {
-      route_name: routeName,
-      assistant: registered.config.assistant,
-      allowed_assistants: [...registered.config.allowedAssistants ?? []],
-      channel_name: registered.channel.name,
-      delivery_supported: typeof registered.channel.deliver === "function"
-    };
-  });
-  return {
-    routes: [
-      { method: "get", path: "/channels", handler: "listChannels" },
-      ...channels.channelRouteBindings(registry.names)
-    ],
-    wrapDispatcher: (inner) => channels.wrapChannelDispatcher({
-      registry,
-      inner,
-      logger: input.deps.logger ?? console
-    }),
-    handlers: {
-      listChannels: async () => ({
-        kind: "json",
-        status: 200,
-        body: { channels: channelInventory }
-      }),
-      handleInboundEvent: async (req) => {
-        const name = req.url.split("?")[0].split("/channels/")[1] ?? "";
-        const registered = registry.get(name);
-        if (!registered) throw SkeinHttpError.notFound(`No channel named "${name}".`);
-        return channels.handleInboundEvent(
-          registered,
-          {
-            method: req.method,
-            url: req.url,
-            headers: req.headers,
-            ...typeof req.body === "string" ? { text: req.body } : {}
-          },
-          pipelineDeps
-        );
-      }
-    }
-  };
-}
-function buildPipelineDeps(deps, service) {
-  let requestFilters;
-  const scopedService = (authContext) => {
-    if (!authContext && !requestFilters) return service();
-    const base = createContext(deps);
-    return createProtocolServiceFromContext({
-      ...base,
-      ...authContext?.user ? { authUser: authContext.user } : {},
-      ...authContext?.scopes ? { authScopes: authContext.scopes } : {},
-      deps: requestFilters && deps.auth ? {
-        ...base.deps,
-        store: createAuthScopedStore(base.deps.store, deps.auth, requestFilters, "threads")
-      } : base.deps
-    });
-  };
-  return {
-    ...deps.store.idempotency ? { idempotency: deps.store.idempotency } : {},
-    clock: () => deps.clock ? deps.clock() : /* @__PURE__ */ new Date(),
-    logger: deps.logger ?? console,
-    // Straight off the run event bus — the same stream `runs.joinStream` serves, without the HTTP
-    // connection per conversation that reaching it from outside would cost.
-    runFrames: { subscribe: (runId) => deps.bus.subscribe(runId) },
-    authorize: async (principal, authz) => {
-      if (!deps.auth) return void 0;
-      const context = {
-        user: {
-          identity: principal.identity,
-          display_name: principal.identity,
-          is_authenticated: true,
-          permissions: principal.permissions ?? [],
-          ...principal.metadata ?? {}
-        },
-        scopes: principal.permissions ?? []
-      };
-      const decision = await deps.auth.authorize({
-        resource: authz.resource,
-        action: authz.action,
-        value: {},
-        context
-      });
-      requestFilters = decision.filters;
-      return context;
-    },
-    ensureThread: async (threadId, metadata, authContext) => {
-      await scopedService(authContext).threads.create({
-        thread_id: threadId,
-        metadata,
-        ifExists: "do_nothing"
-      });
-    },
-    threadStatus: async (threadId) => {
-      const thread = await service().threads.get(threadId).catch(() => null);
-      return thread?.status ?? null;
-    },
-    createRun: async (input) => {
-      const run = await scopedService(input.authContext).runs.createBackground(input.threadId, {
-        assistant_id: input.assistantId,
-        ...input.input !== void 0 ? { input: input.input } : {},
-        ...input.command ? { command: input.command } : {},
-        ...input.ifThreadStatus ? { if_thread_status: [...input.ifThreadStatus] } : {},
-        ...input.multitaskStrategy ? { multitask_strategy: input.multitaskStrategy } : {},
-        ...input.metadata ? { metadata: input.metadata } : {},
-        ...input.webhook ? { webhook: input.webhook } : {},
-        stream_mode: [...input.streamMode]
-      });
-      return { runId: run.run_id };
-    }
-  };
-}
-async function importChannelsPackage(names) {
-  try {
-    return await import("@skein-js/channels");
-  } catch (cause) {
-    throw new SkeinConfigError(
-      `skein.channels configures ${names.join(", ")}, but @skein-js/channels is not installed. Add it as a dependency.`,
-      { cause }
-    );
-  }
-}
-export {
-  resolveChannels
-};