@skein-js/server-kit 0.11.1 → 0.11.2

package/README.md

@@ -34,6 +34,10 @@ handler table.
   / SSE) onto a Node `ServerResponse`, shared by the NestJS + Next.js Pages Router adapters.
 - **Mount prefix** — `stripBasePath`: strip the path an adapter is mounted under before matching the
   route table, for adapters that mount a catch-all and match by hand (NestJS, Next.js).
+- **Logging** — `createConsoleLogger`: the opt-in `Logger` for adapters whose framework owns none
+  (Express, Next.js). `formatLogMeta` / `describeError` are the shared rendering every line-oriented
+  logger needs — a failed run's identity, stack, and `cause` chain — so the framework bridges and the
+  CLI's dev logger can't drift on how a failure reads.
 
 > The route table itself (`skeinRoutes`) is **not** here — it lives with the engine in
 > [`@skein-js/agent-protocol`](../agent-protocol), since it references the handler names. Adapters
@@ -73,11 +77,16 @@ Pass `overrides` to swap in production drivers or an auth engine while keeping t
   replaces any dep (e.g. a Postgres store, an `auth` engine). `createInMemoryDeps` is a
   **`@deprecated`** alias. `graphMapToResolver` / `normalizeEmbeddableGraphs` are the lower-level
   graph→`GraphResolver` helpers.
-- **`resolveProtocolRuntime(options): Promise<ResolvedProtocolRuntime>`** — turn a
+- **`resolveProtocolRuntime(options, frameworkLogger?): Promise<ResolvedProtocolRuntime>`** — turn a
   `{ config } | { deps }` bag (`SkeinRuntimeOptions`) into a live runtime (assistants seeded, worker
   started) — the step every adapter runs before mounting routes. `options.worker`
   (`RunWorkerOptions`) tunes the background worker; `worker.maxConcurrency` is how many queued runs
-  run at once.
+  run at once. `frameworkLogger` is the adapter's own default, applied only when the caller supplied
+  neither `options.logger` nor `deps.logger`; the result's `.logger` is the winner, which the adapter
+  should also use for its transport-fault logging.
+- **`createConsoleLogger(options?): Logger`** — a plain `console.*` logger (`level`, `prefix`), for
+  adapters whose framework owns none. `formatLogMeta(meta)` / `describeError(thrown)` render a failed
+  run's identity, stack, and `cause` chain as text.
 - **`resolveRunConcurrency(explicit?, env?): number`** — the one precedence chain behind
   `worker.maxConcurrency`: explicit value → `SKEIN_RUN_CONCURRENCY` → `N_JOBS_PER_WORKER` →
   `DEFAULT_RUN_CONCURRENCY` (10, matching the LangGraph CLI). The environment is validated even when

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { ProtocolRuntime, ProtocolDeps, Logger, RunWorkerOptions, GraphResolver, ProtocolResponse } from '@skein-js/agent-protocol';
-export { CompiledGraphFactory, DEFAULT_RUN_CONCURRENCY, DEFAULT_SHUTDOWN_GRACE_MS, GraphResolver, ProtocolDeps, ResolvedGraph, RunWorkerOptions } from '@skein-js/agent-protocol';
+import { ProtocolRuntime, Logger, ProtocolDeps, RunWorkerOptions, RunFailureReport, GraphResolver, ProtocolResponse } 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 { ModuleImporter, LanggraphJson, GraphSchemas } from '@skein-js/config';
 import { CorsOptions } from 'cors';
 export { CorsOptions } from 'cors';
@@ -9,7 +9,25 @@ import { SkeinStore } from '@skein-js/core';
 import { ServerResponse } from 'node:http';
 
 interface SkeinRuntimeCommonOptions {
-    logger?: Logger;
+    /**
+     * 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
+     * is the one knob that decides whether a crashed graph is visible at all.
+     *
+     * Precedence, most explicit first:
+     *
+     * | You pass                 | Result                                                            |
+     * | ------------------------ | ----------------------------------------------------------------- |
+     * | a `Logger`               | that logger, overriding any `deps.logger`                          |
+     * | `false`                  | the adapter contributes nothing and installs no default; an injected `deps.logger` still stands |
+     * | nothing                  | `deps.logger` if you injected one, else the adapter's framework default |
+     *
+     * The framework default exists only where the framework owns a logger the host has already
+     * configured: NestJS (`@nestjs/common`'s `Logger`, honoring `app.useLogger()`) and Fastify
+     * (`fastify.log`). Express and Next.js own no such thing, so they stay silent unless you pass one —
+     * `createConsoleLogger()` is the one-liner.
+     */
+    logger?: Logger | false;
     /**
      * 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
@@ -60,12 +78,21 @@ interface ResolvedProtocolRuntime {
     runtime: ProtocolRuntime;
     /** CORS mapped from the config's `http.cors`, or `undefined` for the injected-`deps` path. */
     cors?: CorsOptions;
+    /**
+     * The logger the engine ended up with, after {@link SkeinRuntimeCommonOptions.logger}'s precedence
+     * chain. `undefined` means nothing logs. Adapters read this (rather than `options.logger`) for
+     * their own transport-fault logging, so the engine and the transport can never disagree about
+     * where output goes.
+     */
+    logger?: Logger;
 }
 /** Just the dependencies behind a `{ config } | { deps }` bag — no runtime, no worker. */
 interface ResolvedRuntimeDeps {
     deps: ProtocolDeps;
     /** CORS mapped from the config's `http.cors`, or `undefined` for the injected-`deps` path. */
     cors?: CorsOptions;
+    /** The resolved logger — see {@link ResolvedProtocolRuntime.logger}. */
+    logger?: Logger;
 }
 /**
  * Resolve the `{ config } | { deps }` seam down to a `ProtocolDeps` — injected as-is, or fresh
@@ -73,15 +100,65 @@ interface ResolvedRuntimeDeps {
  * {@link resolveProtocolRuntime} that stops short of building the engine, so the simplified invoke
  * surface (which needs only graphs + store) doesn't seed assistants or start a run worker it will
  * never use.
+ *
+ * `frameworkLogger` is the adapter's own default (Nest's `Logger`, `fastify.log`), used only when the
+ * caller supplied neither `options.logger` nor `deps.logger`.
  */
-declare function resolveRuntimeDeps(options: SkeinRuntimeOptions): Promise<ResolvedRuntimeDeps>;
+declare function resolveRuntimeDeps(options: SkeinRuntimeOptions, frameworkLogger?: Logger): Promise<ResolvedRuntimeDeps>;
 /**
  * Build a `ProtocolRuntime` from adapter options: resolve `deps` (injected, or fresh in-memory
  * drivers from a `langgraph.json`), seed one assistant per declared graph, optionally warm the
  * graphs, and start the background run worker. Returns the runtime plus any CORS derived from the
  * config so the adapter can apply it. The caller owns shutdown (`runtime.worker.stop()`).
+ *
+ * `frameworkLogger` is the adapter's own default — see {@link resolveRuntimeDeps}.
+ */
+declare function resolveProtocolRuntime(options: SkeinRuntimeOptions, frameworkLogger?: Logger): Promise<ResolvedProtocolRuntime>;
+
+/** Levels in ascending severity — the order `level` filters against. */
+declare const LEVELS: readonly ["debug", "info", "warn", "error"];
+type ConsoleLogLevel = (typeof LEVELS)[number];
+interface ConsoleLoggerOptions {
+    /**
+     * Quietest level to emit; anything below it is dropped. Defaults to `"info"`, which covers failed
+     * runs, webhook/rollback problems, and the one-line background-run summaries, while leaving
+     * `debug` off. `"warn"` suppresses the per-run summaries but never hides a failure.
+     */
+    level?: ConsoleLogLevel;
+    /** Prefix on every line, identifying the output as skein's. Defaults to `"skein"`. */
+    prefix?: string;
+}
+/**
+ * A plain console `Logger`. Pass it as an adapter's `logger` to see what skein reports — failed
+ * runs (with the stack and `cause` chain), webhook delivery failures, and background-run summaries:
+ *
+ * ```ts
+ * createExpressServer({ config: "./langgraph.json", logger: createConsoleLogger() });
+ * ```
+ */
+declare function createConsoleLogger(options?: ConsoleLoggerOptions): Logger;
+
+/**
+ * The `run=… thread=… assistant=… node=…` row identifying a failed run. Exported so the framework
+ * bridges, which place the stack in their own logger's dedicated slot rather than appending it to
+ * the message, still render identity identically — adding a field is then one edit, not three.
+ */
+declare function runFailureIdentity(report: RunFailureReport): string;
+/**
+ * Render structured log meta as plain text. Returns `""` when there is nothing to add, so callers can
+ * append unconditionally.
+ *
+ * A `RunFailureReport` renders as its identity row plus the error's stack and `cause` chain — the
+ * failure's *whole* story, since this is the one surface guaranteed to receive it (the wire gets only
+ * what is safe to hand a caller).
+ */
+declare function formatLogMeta(meta: unknown): string;
+
+/**
+ * An error's stack (falling back to `name: message`), its `details` when it carries any, and its
+ * `cause` chain appended. Depth-capped and cycle-safe; never throws.
  */
-declare function resolveProtocolRuntime(options: SkeinRuntimeOptions): Promise<ResolvedProtocolRuntime>;
+declare function describeError(thrown: unknown): string;
 
 /**
  * The one precedence chain for background-run concurrency: an explicit value (a `worker.maxConcurrency`
@@ -292,4 +369,4 @@ declare function sendNodeError(error: unknown, res: ServerResponse, logger?: Log
  */
 declare function stripBasePath(pathname: string, basePath: string): string | null;
 
-export { type CorsSetting, type DevStateCounts, type DevStateSnapshot, type EmbeddableGraph, type InMemoryRuntimeConfig, type LanggraphCorsConfig, type ReloadableInMemoryRuntime, type ResolvedProtocolRuntime, type ResolvedRuntimeDeps, type SkeinRuntimeCommonOptions, type SkeinRuntimeOptions, allowedOrigin, applyNodeCors, corsFromHttpConfig, corsPreflightHeaders, corsResponseHeaders, createInMemoryDeps, describeSnapshot, embedInMemoryGraphs, graphMapToResolver, joinList, loadInMemoryRuntime, loadReloadableInMemoryRuntime, loadSnapshotIntoStore, normalizeEmbeddableGraphs, readLanggraphDevState, resolveProtocolRuntime, resolveRunConcurrency, resolveRuntimeDeps, resolveShutdownGraceMs, sendNodeError, sendNodePreflight, sendNodeResponse, stripBasePath, toCorsOptions };
+export { type ConsoleLogLevel, type ConsoleLoggerOptions, type CorsSetting, type DevStateCounts, type DevStateSnapshot, type EmbeddableGraph, type InMemoryRuntimeConfig, type LanggraphCorsConfig, type ReloadableInMemoryRuntime, type ResolvedProtocolRuntime, type ResolvedRuntimeDeps, type SkeinRuntimeCommonOptions, type SkeinRuntimeOptions, allowedOrigin, applyNodeCors, corsFromHttpConfig, corsPreflightHeaders, corsResponseHeaders, createConsoleLogger, createInMemoryDeps, describeError, describeSnapshot, embedInMemoryGraphs, formatLogMeta, graphMapToResolver, joinList, loadInMemoryRuntime, loadReloadableInMemoryRuntime, loadSnapshotIntoStore, normalizeEmbeddableGraphs, readLanggraphDevState, resolveProtocolRuntime, resolveRunConcurrency, resolveRuntimeDeps, resolveShutdownGraceMs, runFailureIdentity, sendNodeError, sendNodePreflight, sendNodeResponse, stripBasePath, toCorsOptions };

package/dist/index.js

@@ -242,13 +242,19 @@ function resolveShutdownGraceMs(explicit, env = process.env) {
 }
 
 // src/resolve-runtime.ts
-async function resolveRuntimeDeps(options) {
-  if (options.deps) return { deps: options.deps };
-  const loaded = await loadInMemoryRuntime(options.config, options.importModule);
-  return { deps: loaded.deps, cors: loaded.cors };
-}
-async function resolveProtocolRuntime(options) {
-  const { deps, cors: corsFromConfig } = await resolveRuntimeDeps(options);
+function resolveLogger(option, injected, frameworkLogger) {
+  if (injected) return injected;
+  if (option === false) return void 0;
+  return option ?? frameworkLogger;
+}
+async function resolveRuntimeDeps(options, frameworkLogger) {
+  const loaded = options.deps ? { deps: options.deps, cors: void 0 } : await 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, logger };
+}
+async function resolveProtocolRuntime(options, frameworkLogger) {
+  const { deps, cors: corsFromConfig, logger } = await resolveRuntimeDeps(options, frameworkLogger);
   const runtime = createProtocolRuntime(deps, {
     worker: {
       ...options.worker,
@@ -261,13 +267,126 @@ async function resolveProtocolRuntime(options) {
     await Promise.all(
       deps.graphs.ids.map(
         (graphId) => deps.graphs.load(graphId).catch((error) => {
-          options.logger?.warn(`Failed to warm graph "${graphId}".`, error);
+          logger?.warn(`Failed to warm graph "${graphId}".`, error);
         })
       )
     );
   }
   runtime.worker.start();
-  return { runtime, cors: corsFromConfig };
+  return { runtime, cors: corsFromConfig, logger };
+}
+
+// src/log-meta.ts
+import { isRunFailureReport } from "@skein-js/agent-protocol";
+
+// src/describe-error.ts
+var MAX_CAUSE_DEPTH = 5;
+function readProperty(source, key) {
+  try {
+    return source[key];
+  } catch {
+    return void 0;
+  }
+}
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return void 0;
+  }
+}
+function describe(thrown, depth, seen) {
+  if (!(thrown instanceof Error)) {
+    return typeof thrown === "object" && thrown !== null ? safeStringify(thrown) ?? String(thrown) : String(thrown);
+  }
+  const stack = readProperty(thrown, "stack");
+  let described = typeof stack === "string" ? stack : `${thrown.name}: ${thrown.message}`;
+  const details = readProperty(thrown, "details");
+  if (details !== void 0) {
+    const rendered = safeStringify(details);
+    if (rendered !== void 0) described += `
+details: ${rendered}`;
+  }
+  if (depth >= MAX_CAUSE_DEPTH || seen.has(thrown)) return described;
+  seen.add(thrown);
+  const cause = readProperty(thrown, "cause");
+  if (cause === void 0) return described;
+  return `${described}
+caused by: ${describe(cause, depth + 1, seen)}`;
+}
+function describeError(thrown) {
+  return describe(thrown, 0, /* @__PURE__ */ new WeakSet());
+}
+
+// src/log-meta.ts
+function runFailureIdentity(report) {
+  return [
+    `run=${report.runId}`,
+    `thread=${report.threadId}`,
+    `assistant=${report.assistantId}`,
+    // Omitted entirely when LangGraph named no node — no `unknown` placeholder, no guess.
+    ...report.failingNodes.length > 0 ? [`node=${report.failingNodes.join(",")}`] : []
+  ].join(" ");
+}
+function safeString(value) {
+  try {
+    return String(value);
+  } catch {
+    return Object.prototype.toString.call(value);
+  }
+}
+function safeStringify2(value) {
+  try {
+    return JSON.stringify(value) ?? safeString(value);
+  } catch {
+    return safeString(value);
+  }
+}
+function renderRecord(meta) {
+  let entries;
+  try {
+    entries = Object.entries(meta);
+  } catch {
+    return safeString(meta);
+  }
+  return entries.map(([key, value]) => {
+    const rendered = typeof value === "object" && value !== null ? safeStringify2(value) : safeString(value);
+    return `${key}=${rendered}`;
+  }).join(" ");
+}
+function formatLogMeta(meta) {
+  if (meta === void 0 || meta === null) return "";
+  if (isRunFailureReport(meta)) return `${runFailureIdentity(meta)}
+${describeError(meta.error)}`;
+  if (meta instanceof Error) return describeError(meta);
+  if (typeof meta === "object") return renderRecord(meta);
+  return safeString(meta);
+}
+
+// src/console-logger.ts
+var LEVELS = ["debug", "info", "warn", "error"];
+function createConsoleLogger(options = {}) {
+  const prefix = options.prefix ?? "skein";
+  const configured = LEVELS.indexOf(options.level ?? "info");
+  const threshold = configured === -1 ? LEVELS.indexOf("info") : configured;
+  function emit(level, write) {
+    const rank = LEVELS.indexOf(level);
+    if (rank < threshold) return () => {
+    };
+    return (message, meta) => {
+      const rendered = formatLogMeta(meta);
+      write(`${prefix} ${level}: ${message}${rendered ? `
+${rendered}` : ""}`);
+    };
+  }
+  return {
+    // Bound to `console` rather than passed by reference so a host that swaps `console.log` later
+    // (test harnesses do) is still honored at call time.
+    debug: emit("debug", (line) => console.debug(line)),
+    info: emit("info", (line) => console.log(line)),
+    warn: emit("warn", (line) => console.warn(line)),
+    error: emit("error", (line) => console.error(line))
+  };
 }
 
 // src/index.ts
@@ -720,9 +839,12 @@ export {
   corsFromHttpConfig,
   corsPreflightHeaders,
   corsResponseHeaders,
+  createConsoleLogger,
   createInMemoryDeps,
+  describeError,
   describeSnapshot,
   embedInMemoryGraphs,
+  formatLogMeta,
   graphMapToResolver,
   joinList,
   loadInMemoryRuntime,
@@ -734,6 +856,7 @@ export {
   resolveRunConcurrency,
   resolveRuntimeDeps,
   resolveShutdownGraceMs,
+  runFailureIdentity,
   sendNodeError,
   sendNodePreflight,
   sendNodeResponse,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/server-kit",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "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>",
@@ -44,10 +44,10 @@
     "cors": "^2.8.5",
     "superjson": "^2.2.6",
     "zod": "^3.25.76",
-    "@skein-js/agent-protocol": "0.11.1",
-    "@skein-js/config": "0.11.1",
-    "@skein-js/core": "0.11.1",
-    "@skein-js/storage-memory": "0.11.1"
+    "@skein-js/agent-protocol": "0.11.2",
+    "@skein-js/storage-memory": "0.11.2",
+    "@skein-js/config": "0.11.2",
+    "@skein-js/core": "0.11.2"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0"