@skein-js/runtime 0.6.3 → 0.7.0

package/README.md

@@ -50,6 +50,32 @@ Graph hot-reload (`reloadGraphs()`) works in every mode; `snapshotState`/`hydrat
 > which uses the in-memory runtime under the hood); `buildRuntime` is the path the CLI uses to add
 > Postgres/Redis.
 
+## In-code embedding (Postgres + Redis)
+
+`buildRuntime` assembles durable deps **from a `langgraph.json`**. `embedPostgresGraphs` assembles the
+same durable deps **from a graph you already hold in code** — the persistent counterpart to
+[`embedInMemoryGraphs`](../server-kit) (which wires only in-memory drivers). Because it owns
+pools/connections, it's `async` and returns a `dispose()`:
+
+```ts
+import { createExpressServer } from "@skein-js/express";
+import { embedPostgresGraphs } from "@skein-js/runtime";
+import { graph } from "./my-graph.js";
+
+const { deps, dispose } = await embedPostgresGraphs({ agent: graph }); // reads POSTGRES_URI / REDIS_URI
+const server = await createExpressServer({ deps });
+await server.listen(2024);
+// …on shutdown:
+await dispose();
+```
+
+Postgres is required (`POSTGRES_URI` or `postgresUri`). **Redis is optional** — with no `redisUri` /
+`REDIS_URI`, the run queue + event bus fall back to in-memory: state survives a restart, but you're
+limited to a **single instance** (the queue is process-local; streaming isn't fanned across instances).
+Options mirror the low-level knobs: `index` (pgvector), `ttl`, `poolMax`, `sslNoVerify`, and `overrides`
+for non-driver deps (`auth`/`logger`/…). See [docs/embedding.md](../../docs/embedding.md) for the full
+walkthrough.
+
 ## Install
 
 ```bash
@@ -62,10 +88,15 @@ TypeScript graphs/embedders requires passing an `importModule` (the CLI injects
 ## API
 
 - **`buildRuntime(options): Promise<SkeinRuntime>`** — `options`:
-  `{ configPath, store, queue, importModule? }`.
+  `{ configPath, store, queue, importModule? }`. Durable deps **from a `langgraph.json`**.
 - **`interface SkeinRuntime`** — `{ deps, cors?, reloadGraphs(), dispose(), snapshotState?(), hydrateState?() }`
   (the last two only in all-memory mode).
 - **`type StoreDriver`** = `"memory" | "postgres"` · **`type QueueDriver`** = `"memory" | "redis"`.
+- **`embedPostgresGraphs(graphs, options?): Promise<EmbeddedPostgresRuntime>`** — durable deps **from
+  graphs in code** (Postgres + `PostgresSaver`, Redis when configured). Returns `{ deps, dispose() }`.
+  `options`: `{ postgresUri?, redisUri?, index?, ttl?, poolMax?, sslNoVerify?, overrides? }`.
+- **`interface EmbedPostgresGraphsOptions`** · **`interface EmbeddedPostgresRuntime`** ·
+  re-exported **`type EmbeddableGraph`** (from `@skein-js/server-kit`).
 - **`class RuntimeConfigError`** — thrown when a driver's env var or `store.index.embed` can't be
   resolved.
 - **`resolveEmbed(embed, { configDir, importModule? })`** — resolves a `langgraph.json`

package/dist/index.d.ts

@@ -1,13 +1,15 @@
-import { ProtocolDeps } from '@skein-js/agent-protocol';
+import { ProtocolDeps, GraphResolver } from '@skein-js/agent-protocol';
 import { ModuleImporter, GraphSchemas } from '@skein-js/config';
-import { DevStateSnapshot } from '@skein-js/server-kit';
+import { DevStateSnapshot, EmbeddableGraph } from '@skein-js/server-kit';
+export { EmbeddableGraph } from '@skein-js/server-kit';
 import { CorsOptions } from 'cors';
-import { EmbedFunction } from '@skein-js/storage-postgres';
+import { PostgresSkeinStoreOptions, StoreIndexConfig, EmbedFunction } from '@skein-js/storage-postgres';
 
 /** Where protocol resources (assistants/threads/runs/store) and checkpoints are persisted. */
 type StoreDriver = "memory" | "postgres";
 /** Where background runs are queued and stream frames are fanned out. */
 type QueueDriver = "memory" | "redis";
+/** Options for {@link buildRuntime}: which `langgraph.json` to load and which drivers to wire. */
 interface BuildRuntimeOptions {
     /** Absolute path to `langgraph.json`. */
     configPath: string;
@@ -23,6 +25,10 @@ interface BuildRuntimeOptions {
     /** `"memory"` (default dev) or `"redis"` (reads `REDIS_URI`). */
     queue: QueueDriver;
 }
+/**
+ * The result of {@link buildRuntime}: assembled deps for any adapter's `{ deps }` seam, plus the
+ * lifecycle hooks (`reloadGraphs`, `dispose`, and — in all-memory mode — state snapshot/hydrate).
+ */
 interface SkeinRuntime {
     /** Assembled dependency bundle to pass as `createExpressServer({ deps })`. */
     deps: ProtocolDeps;
@@ -40,6 +46,67 @@ interface SkeinRuntime {
 /** Assemble a {@link SkeinRuntime} for the requested driver combination. */
 declare function buildRuntime(options: BuildRuntimeOptions): Promise<SkeinRuntime>;
 
+/** Store-item TTL policy — derived from the store's public option so runtime needn't depend on core. */
+type StoreTtl = NonNullable<PostgresSkeinStoreOptions["ttl"]>;
+
+/** Options for {@link embedPostgresGraphs} — connection strings, semantic search, TTL, and overrides. */
+interface EmbedPostgresGraphsOptions {
+    /** Postgres connection string. Defaults to `process.env.POSTGRES_URI`; throws if neither is set. */
+    postgresUri?: string;
+    /**
+     * Redis connection string. Defaults to `process.env.REDIS_URI`. When **absent**, the run queue and
+     * event bus fall back to in-memory — a single durable instance: state survives a restart, but the
+     * run queue is process-local and streaming is not fanned across instances, so it is **not
+     * horizontally scalable**. Set a Redis URL to run more than one instance.
+     */
+    redisUri?: string;
+    /**
+     * pgvector semantic-search config for the long-term store — a resolved embedder (`dims` + `embed`).
+     * Omitted → store search falls back to naive text matching.
+     */
+    index?: StoreIndexConfig;
+    /** Store-item TTL/expiry policy (with a background sweep). Omitted → items never expire. */
+    ttl?: StoreTtl;
+    /** Max connections per pool (skein opens two — store + saver). Defaults to env `PG_POOL_MAX`. */
+    poolMax?: number;
+    /** Disable TLS cert verification (self-signed managed cert). Defaults to env `DATABASE_SSL_NO_VERIFY`. */
+    sslNoVerify?: boolean;
+    /**
+     * Replace or add any NON-driver dep — `auth`, `logger`, `clock`, `logRunActivity`, `runTimeoutMs`,
+     * `webhookDispatcher`. The drivers (`store`/`queue`/`bus`/`checkpointer`) and `graphs` are owned by
+     * this helper and excluded, so a stray override can't void the durable wiring or the graph source.
+     */
+    overrides?: Omit<Partial<ProtocolDeps>, "graphs" | "store" | "queue" | "bus" | "checkpointer">;
+}
+/** The result of {@link embedPostgresGraphs}: the assembled deps and a `dispose()` for the pools it owns. */
+interface EmbeddedPostgresRuntime {
+    /** Assembled deps for any adapter's `{ deps }` seam. */
+    deps: ProtocolDeps;
+    /** Tear down the Postgres pools + any Redis connections + the TTL sweeper. Call on shutdown. */
+    dispose(): Promise<void>;
+}
+/**
+ * Build a durable `ProtocolDeps` around graphs you already hold in code — Postgres store +
+ * `PostgresSaver`, plus Redis queue/bus when a Redis URL is configured — and a `dispose()` to release
+ * the pools/connections it opens. Pass a map of compiled graphs (or factories), or a ready
+ * {@link GraphResolver}; hand the result's `deps` to any adapter's `{ deps }` seam:
+ *
+ * ```ts
+ * import { embedPostgresGraphs } from "@skein-js/runtime";
+ * import { createExpressServer } from "@skein-js/express";
+ *
+ * const { deps, dispose } = await embedPostgresGraphs({ agent: graph }); // reads POSTGRES_URI / REDIS_URI
+ * const server = await createExpressServer({ deps });
+ * await server.listen(2024);
+ * // …on shutdown:
+ * await dispose();
+ * ```
+ *
+ * Postgres is required (`POSTGRES_URI` or `options.postgresUri`). Redis is optional — see
+ * {@link EmbedPostgresGraphsOptions.redisUri} for the single-instance caveat when it's omitted.
+ */
+declare function embedPostgresGraphs(graphs: GraphResolver | Record<string, EmbeddableGraph>, options?: EmbedPostgresGraphsOptions): Promise<EmbeddedPostgresRuntime>;
+
 /** Thrown when a selected driver's connection env or `store.index.embed` config can't be resolved. */
 declare class RuntimeConfigError extends Error {
     constructor(message: string);
@@ -64,8 +131,13 @@ declare function isCustomFunctionPath(embed: string): boolean;
  * it must pin this package into the production image explicitly. Custom-function paths return undefined
  * (they are bundled), as do unknown providers.
  */
-declare function embedRuntimePackage(embed: string): string | undefined;
+declare function providerEmbedPackage(embed: string): string | undefined;
+/**
+ * @deprecated Renamed to {@link providerEmbedPackage} — it returns the npm package a `provider:model`
+ * embed needs installed, not a verb. Kept for back-compat; slated for removal in a future major.
+ */
+declare const embedRuntimePackage: typeof providerEmbedPackage;
 /** Resolve a `store.index.embed` value to an `EmbedFunction`, honoring both LangGraph forms. */
 declare function resolveEmbed(embed: string, options: ResolveEmbedOptions): Promise<EmbedFunction>;
 
-export { type BuildRuntimeOptions, type QueueDriver, type ResolveEmbedOptions, RuntimeConfigError, type SkeinRuntime, type StoreDriver, buildRuntime, embedRuntimePackage, isCustomFunctionPath, resolveEmbed };
+export { type BuildRuntimeOptions, type EmbedPostgresGraphsOptions, type EmbeddedPostgresRuntime, type QueueDriver, type ResolveEmbedOptions, RuntimeConfigError, type SkeinRuntime, type StoreDriver, buildRuntime, embedPostgresGraphs, embedRuntimePackage, isCustomFunctionPath, providerEmbedPackage, resolveEmbed };

package/dist/index.js

@@ -1,16 +1,18 @@
 // src/build-runtime.ts
 import { MemorySaver } from "@langchain/langgraph";
-import { PostgresSaver } from "@langchain/langgraph-checkpoint-postgres";
 import {
   loadAuthEngine,
   loadConfig
 } from "@skein-js/config";
-import { RedisRunEventBus, RedisRunQueue } from "@skein-js/redis";
 import {
   corsFromHttpConfig,
   loadReloadableInMemoryRuntime
 } from "@skein-js/server-kit";
 import { MemoryRunEventBus, MemoryRunQueue, MemorySkeinStore } from "@skein-js/storage-memory";
+
+// src/drivers.ts
+import { PostgresSaver } from "@langchain/langgraph-checkpoint-postgres";
+import { RedisRunEventBus, RedisRunQueue } from "@skein-js/redis";
 import {
   createPostgresPool,
   PostgresSkeinStore
@@ -24,6 +26,64 @@ var RuntimeConfigError = class extends Error {
   }
 };
 
+// src/drivers.ts
+async function runDisposers(disposers) {
+  await Promise.allSettled(disposers.map((dispose) => dispose()));
+}
+function requireEnv(name, driver) {
+  const value = process.env[name];
+  if (!value) {
+    throw new RuntimeConfigError(`The "${driver}" driver requires ${name} to be set.`);
+  }
+  return value;
+}
+function postgresConnectionOptions() {
+  const options = {};
+  const rawMax = process.env["PG_POOL_MAX"];
+  if (rawMax !== void 0 && rawMax.trim() !== "") {
+    const max = Number(rawMax);
+    if (!Number.isInteger(max) || max <= 0) {
+      throw new RuntimeConfigError(`PG_POOL_MAX must be a positive integer (got "${rawMax}").`);
+    }
+    options.poolMax = max;
+  }
+  const noVerify = process.env["DATABASE_SSL_NO_VERIFY"];
+  if (noVerify === "1" || noVerify?.toLowerCase() === "true") options.sslNoVerify = true;
+  return options;
+}
+async function connectPostgresStore(args) {
+  const { url, index, ttl, connectionOptions, disposers } = args;
+  const store = await PostgresSkeinStore.connect(url, {
+    ...index ? { index } : {},
+    ...ttl ? { ttl } : {},
+    ...connectionOptions
+  });
+  disposers.push(() => store.close());
+  await store.migrate();
+  const checkpointer = new PostgresSaver(createPostgresPool(url, connectionOptions));
+  disposers.push(() => checkpointer.end());
+  await checkpointer.setup();
+  return { store, checkpointer };
+}
+function connectRedisQueue(args) {
+  const { url, disposers } = args;
+  const queue = new RedisRunQueue(url);
+  disposers.push(() => queue.dispose());
+  const bus = new RedisRunEventBus(url);
+  disposers.push(() => bus.dispose());
+  return { queue, bus };
+}
+function startStoreTtlSweeper(store, ttl, disposers) {
+  const everyMs = (ttl.sweepIntervalMinutes ?? 60) * 6e4;
+  const sweeper = setInterval(() => {
+    store.store.sweepExpired().catch((error) => {
+      console.error("skein: store TTL sweep failed", error);
+    });
+  }, everyMs);
+  sweeper.unref();
+  disposers.push(async () => clearInterval(sweeper));
+}
+
 // src/resolve-embed.ts
 import { pathToFileURL } from "url";
 import { parseGraphSpec } from "@skein-js/config";
@@ -52,12 +112,13 @@ function isCustomFunctionPath(embed) {
   const head = embed.split(":", 1)[0] ?? "";
   return head.startsWith(".") || head.startsWith("/") || /\.([mc]?[jt]s|py)$/.test(head);
 }
-function embedRuntimePackage(embed) {
+function providerEmbedPackage(embed) {
   if (isCustomFunctionPath(embed)) return void 0;
   const separator = embed.indexOf(":");
   if (separator === -1) return void 0;
   return PROVIDERS[embed.slice(0, separator)]?.package;
 }
+var embedRuntimePackage = providerEmbedPackage;
 async function resolvePathEmbed(embed, options) {
   const { sourceFile, exportSymbol } = parseGraphSpec(embed, options.configDir);
   const importer = options.importModule ?? ((file) => import(pathToFileURL(file).href));
@@ -106,27 +167,6 @@ async function resolveEmbed(embed, options) {
 }
 
 // src/build-runtime.ts
-function requireEnv(name, driver) {
-  const value = process.env[name];
-  if (!value) {
-    throw new RuntimeConfigError(`The "${driver}" driver requires ${name} to be set.`);
-  }
-  return value;
-}
-function postgresConnectionOptions() {
-  const options = {};
-  const rawMax = process.env["PG_POOL_MAX"];
-  if (rawMax !== void 0 && rawMax.trim() !== "") {
-    const max = Number(rawMax);
-    if (!Number.isInteger(max) || max <= 0) {
-      throw new RuntimeConfigError(`PG_POOL_MAX must be a positive integer (got "${rawMax}").`);
-    }
-    options.poolMax = max;
-  }
-  const noVerify = process.env["DATABASE_SSL_NO_VERIFY"];
-  if (noVerify === "1" || noVerify?.toLowerCase() === "true") options.sslNoVerify = true;
-  return options;
-}
 function reroutableGraphResolver(initial) {
   let current = initial;
   return {
@@ -167,57 +207,24 @@ async function buildRuntime(options) {
   const first = await loadConfig({ configPath, importModule, staticSchemas: schemas });
   const { resolver, reroute } = reroutableGraphResolver(first.graphs);
   const disposers = [];
-  const disposeAll = async () => {
-    await Promise.allSettled(disposers.map((dispose) => dispose()));
-  };
+  const disposeAll = () => runDisposers(disposers);
   try {
     const storeTtl = resolveStoreTtl(first.config.store?.ttl);
-    const { skeinStore, checkpointer } = await (async () => {
-      if (store === "postgres") {
-        const databaseUrl = requireEnv("POSTGRES_URI", "postgres");
-        const index = await resolveStoreIndex(first.config.store?.index, {
-          configDir: first.configDir,
-          importModule
-        });
-        const connectionOptions = postgresConnectionOptions();
-        const pgStore = await PostgresSkeinStore.connect(databaseUrl, {
-          ...index ? { index } : {},
-          ...storeTtl ? { ttl: storeTtl } : {},
-          ...connectionOptions
-        });
-        disposers.push(() => pgStore.close());
-        await pgStore.migrate();
-        const saver = new PostgresSaver(createPostgresPool(databaseUrl, connectionOptions));
-        disposers.push(() => saver.end());
-        await saver.setup();
-        return { skeinStore: pgStore, checkpointer: saver };
-      }
-      return {
-        skeinStore: new MemorySkeinStore(storeTtl ? { ttl: storeTtl } : void 0),
-        checkpointer: new MemorySaver()
-      };
-    })();
-    if (storeTtl) {
-      const everyMs = (storeTtl.sweepIntervalMinutes ?? 60) * 6e4;
-      const sweeper = setInterval(() => {
-        skeinStore.store.sweepExpired().catch((error) => {
-          console.error("skein: store TTL sweep failed", error);
-        });
-      }, everyMs);
-      sweeper.unref();
-      disposers.push(async () => clearInterval(sweeper));
-    }
-    const { runQueue, bus } = (() => {
-      if (queue === "redis") {
-        const redisUrl = requireEnv("REDIS_URI", "redis");
-        const redisQueue = new RedisRunQueue(redisUrl);
-        disposers.push(() => redisQueue.dispose());
-        const redisBus = new RedisRunEventBus(redisUrl);
-        disposers.push(() => redisBus.dispose());
-        return { runQueue: redisQueue, bus: redisBus };
-      }
-      return { runQueue: new MemoryRunQueue(), bus: new MemoryRunEventBus() };
-    })();
+    const { store: skeinStore, checkpointer } = store === "postgres" ? await connectPostgresStore({
+      url: requireEnv("POSTGRES_URI", "postgres"),
+      index: await resolveStoreIndex(first.config.store?.index, {
+        configDir: first.configDir,
+        importModule
+      }),
+      ttl: storeTtl,
+      connectionOptions: postgresConnectionOptions(),
+      disposers
+    }) : {
+      store: new MemorySkeinStore(storeTtl ? { ttl: storeTtl } : void 0),
+      checkpointer: new MemorySaver()
+    };
+    if (storeTtl) startStoreTtlSweeper(skeinStore, storeTtl, disposers);
+    const { queue: runQueue, bus } = queue === "redis" ? connectRedisQueue({ url: requireEnv("REDIS_URI", "redis"), disposers }) : { queue: new MemoryRunQueue(), bus: new MemoryRunEventBus() };
     const deps = {
       store: skeinStore,
       graphs: resolver,
@@ -252,10 +259,63 @@ function resolveStoreTtl(raw) {
   }
   return Object.keys(ttl).length > 0 ? ttl : void 0;
 }
+
+// src/embed-postgres-graphs.ts
+import { normalizeEmbeddableGraphs } from "@skein-js/server-kit";
+import { MemoryRunEventBus as MemoryRunEventBus2, MemoryRunQueue as MemoryRunQueue2 } from "@skein-js/storage-memory";
+async function embedPostgresGraphs(graphs, options = {}) {
+  const disposers = [];
+  const dispose = () => runDisposers(disposers);
+  try {
+    if (options.poolMax !== void 0 && (!Number.isInteger(options.poolMax) || options.poolMax <= 0)) {
+      throw new RuntimeConfigError(`poolMax must be a positive integer (got ${options.poolMax}).`);
+    }
+    const connectionOptions = {
+      ...postgresConnectionOptions(),
+      ...options.poolMax !== void 0 ? { poolMax: options.poolMax } : {},
+      ...options.sslNoVerify !== void 0 ? { sslNoVerify: options.sslNoVerify } : {}
+    };
+    const { store, checkpointer } = await connectPostgresStore({
+      // A blank explicit URI is treated as "not provided" so it falls through to `requireEnv` and gets
+      // the actionable RuntimeConfigError, rather than an opaque `pg` error from connecting to "".
+      url: blankToUndefined(options.postgresUri) ?? requireEnv("POSTGRES_URI", "postgres"),
+      index: options.index,
+      ttl: options.ttl,
+      connectionOptions,
+      disposers
+    });
+    if (options.ttl) startStoreTtlSweeper(store, options.ttl, disposers);
+    const redisUrl = blankToUndefined(options.redisUri) ?? blankToUndefined(process.env["REDIS_URI"]);
+    if (!redisUrl) {
+      console.warn(
+        "skein: embedPostgresGraphs has no Redis URL (redisUri / REDIS_URI) \u2014 using an in-memory run queue + event bus. State is durable in Postgres, but this is a single instance: the queue is process-local and streaming isn't fanned across instances. Set a Redis URL to scale out."
+      );
+    }
+    const { queue, bus } = redisUrl ? connectRedisQueue({ url: redisUrl, disposers }) : { queue: new MemoryRunQueue2(), bus: new MemoryRunEventBus2() };
+    const deps = {
+      store,
+      graphs: normalizeEmbeddableGraphs(graphs),
+      queue,
+      bus,
+      checkpointer,
+      ...options.overrides
+      // spread LAST, mirroring embedInMemoryGraphs
+    };
+    return { deps, dispose };
+  } catch (error) {
+    await dispose();
+    throw error;
+  }
+}
+function blankToUndefined(value) {
+  return value && value.trim() !== "" ? value : void 0;
+}
 export {
   RuntimeConfigError,
   buildRuntime,
+  embedPostgresGraphs,
   embedRuntimePackage,
   isCustomFunctionPath,
+  providerEmbedPackage,
   resolveEmbed
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/runtime",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Assembles skein-js ProtocolDeps from langgraph.json + selected drivers (memory/Postgres/Redis).",
   "license": "Apache-2.0",
   "author": "Maina Wycliffe <wmmaina7@gmail.com>",
@@ -42,12 +42,12 @@
   },
   "dependencies": {
     "cors": "^2.8.5",
-    "@skein-js/agent-protocol": "0.6.3",
-    "@skein-js/redis": "0.6.3",
-    "@skein-js/config": "0.6.3",
-    "@skein-js/server-kit": "0.6.3",
-    "@skein-js/storage-memory": "0.6.3",
-    "@skein-js/storage-postgres": "0.6.3"
+    "@skein-js/config": "0.7.0",
+    "@skein-js/redis": "0.7.0",
+    "@skein-js/server-kit": "0.7.0",
+    "@skein-js/storage-memory": "0.7.0",
+    "@skein-js/agent-protocol": "0.7.0",
+    "@skein-js/storage-postgres": "0.7.0"
   },
   "peerDependencies": {
     "@langchain/langgraph": "^1.4.0",
@@ -58,7 +58,7 @@
     "@langchain/langgraph": "^1.4.0",
     "@langchain/langgraph-checkpoint-postgres": "^1.0.4",
     "@types/cors": "^2.8.17",
-    "@skein-js/test-support": "0.6.3"
+    "@skein-js/test-support": "0.7.0"
   },
   "publishConfig": {
     "access": "public"