@skein-js/runtime 0.3.0 → 0.5.0

package/README.md

@@ -20,8 +20,8 @@ import { createExpressServer } from "@skein-js/express";
 
 const runtime = await buildRuntime({
   configPath: "/abs/path/to/langgraph.json",
-  store: "postgres", // "memory" | "postgres"  (postgres reads DATABASE_URL)
-  queue: "redis", //    "memory" | "redis"     (redis reads REDIS_URL)
+  store: "postgres", // "memory" | "postgres"  (postgres reads POSTGRES_URI)
+  queue: "redis", //    "memory" | "redis"     (redis reads REDIS_URI)
 });
 
 const server = await createExpressServer({ deps: runtime.deps, cors: runtime.cors });
@@ -33,13 +33,13 @@ await runtime.dispose();
 `store` and `queue` are **required** (no defaults — the CLI supplies its own flag defaults). The
 driver branches:
 
-- **`store: "postgres"`** connects `PostgresSkeinStore` (from `DATABASE_URL`), runs its migrations,
+- **`store: "postgres"`** connects `PostgresSkeinStore` (from `POSTGRES_URI`), runs its migrations,
   and uses `PostgresSaver` as the LangGraph checkpointer.
-- **`queue: "redis"`** uses the BullMQ run queue + Redis Streams/pub-sub event bus (from `REDIS_URL`).
+- **`queue: "redis"`** uses the BullMQ run queue + Redis Streams/pub-sub event bus (from `REDIS_URI`).
 - **`store: "memory"` + `queue: "memory"`** delegates to [`@skein-js/express`](../server-express)'s
   reloadable in-memory runtime, so `skein dev`'s hot-reload and cross-restart state persistence work.
 
-A missing `DATABASE_URL` / `REDIS_URL` throws `RuntimeConfigError`; if assembly fails part-way, any
+A missing `POSTGRES_URI` / `REDIS_URI` throws `RuntimeConfigError`; if assembly fails part-way, any
 resources already created are disposed before rethrowing, so a failed build leaks nothing.
 
 Graph hot-reload (`reloadGraphs()`) works in every mode; `snapshotState`/`hydrateState` are present

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ProtocolDeps } from '@skein-js/agent-protocol';
-import { ModuleImporter } from '@skein-js/config';
+import { ModuleImporter, GraphSchemas } from '@skein-js/config';
 import { DevStateSnapshot } from '@skein-js/express';
 import { CorsOptions } from 'cors';
 import { EmbedFunction } from '@skein-js/storage-postgres';
@@ -13,9 +13,14 @@ interface BuildRuntimeOptions {
     configPath: string;
     /** TS-capable importer (e.g. the CLI's vite loader). Omitted for plain JS/Node resolution. */
     importModule?: ModuleImporter;
-    /** `"memory"` (default dev) or `"postgres"` (reads `DATABASE_URL`). */
+    /**
+     * Precomputed graph schemas (from `skein build`) for a pre-compiled image — forwarded to
+     * `loadConfig` so schema introspection is a map lookup, never a TypeScript parse. Omitted for dev.
+     */
+    schemas?: Record<string, GraphSchemas>;
+    /** `"memory"` (default dev) or `"postgres"` (reads `POSTGRES_URI`). */
     store: StoreDriver;
-    /** `"memory"` (default dev) or `"redis"` (reads `REDIS_URL`). */
+    /** `"memory"` (default dev) or `"redis"` (reads `REDIS_URI`). */
     queue: QueueDriver;
 }
 interface SkeinRuntime {
@@ -46,7 +51,21 @@ interface ResolveEmbedOptions {
     /** TS-capable importer (the CLI's vite loader) for a custom-function `.ts` path. */
     importModule?: ModuleImporter;
 }
+/**
+ * Whether a `store.index.embed` value is a custom-function path (`"./embed.ts:fn"`) rather than a
+ * `"provider:model"` string — it looks like a path (starts with `.`/`/`) or names a source file.
+ * Exported so `skein build` knows which embed forms to bundle (paths) vs leave as provider strings.
+ */
+declare function isCustomFunctionPath(embed: string): boolean;
+/**
+ * The npm package a `store.index.embed` value needs **installed at runtime**, or undefined. A
+ * `provider:model` embed dynamically imports `@langchain/<provider>` (see {@link resolveProviderEmbed}),
+ * but that package is never imported by graph code, so `skein build` won't discover it while bundling —
+ * 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;
 /** 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, resolveEmbed };
+export { type BuildRuntimeOptions, type QueueDriver, type ResolveEmbedOptions, RuntimeConfigError, type SkeinRuntime, type StoreDriver, buildRuntime, embedRuntimePackage, isCustomFunctionPath, resolveEmbed };

package/dist/index.js

@@ -52,6 +52,12 @@ function isCustomFunctionPath(embed) {
   const head = embed.split(":", 1)[0] ?? "";
   return head.startsWith(".") || head.startsWith("/") || /\.([mc]?[jt]s|py)$/.test(head);
 }
+function embedRuntimePackage(embed) {
+  if (isCustomFunctionPath(embed)) return void 0;
+  const separator = embed.indexOf(":");
+  if (separator === -1) return void 0;
+  return PROVIDERS[embed.slice(0, separator)]?.package;
+}
 async function resolvePathEmbed(embed, options) {
   const { sourceFile, exportSymbol } = parseGraphSpec(embed, options.configDir);
   const importer = options.importModule ?? ((file) => import(pathToFileURL(file).href));
@@ -145,9 +151,9 @@ async function resolveStoreIndex(index, options) {
   return { dims: index.dims, fields: index.fields, embed };
 }
 async function buildRuntime(options) {
-  const { configPath, importModule, store, queue } = options;
+  const { configPath, importModule, store, queue, schemas } = options;
   if (store === "memory" && queue === "memory") {
-    const runtime = await loadReloadableInMemoryRuntime(configPath, importModule);
+    const runtime = await loadReloadableInMemoryRuntime(configPath, importModule, schemas);
     return {
       deps: runtime.deps,
       cors: runtime.cors,
@@ -158,16 +164,17 @@ async function buildRuntime(options) {
       hydrateState: (snapshot) => runtime.hydrateState(snapshot)
     };
   }
-  const first = await loadConfig({ configPath, importModule });
+  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()));
   };
   try {
+    const storeTtl = resolveStoreTtl(first.config.store?.ttl);
     const { skeinStore, checkpointer } = await (async () => {
       if (store === "postgres") {
-        const databaseUrl = requireEnv("DATABASE_URL", "postgres");
+        const databaseUrl = requireEnv("POSTGRES_URI", "postgres");
         const index = await resolveStoreIndex(first.config.store?.index, {
           configDir: first.configDir,
           importModule
@@ -175,6 +182,7 @@ async function buildRuntime(options) {
         const connectionOptions = postgresConnectionOptions();
         const pgStore = await PostgresSkeinStore.connect(databaseUrl, {
           ...index ? { index } : {},
+          ...storeTtl ? { ttl: storeTtl } : {},
           ...connectionOptions
         });
         disposers.push(() => pgStore.close());
@@ -184,11 +192,24 @@ async function buildRuntime(options) {
         await saver.setup();
         return { skeinStore: pgStore, checkpointer: saver };
       }
-      return { skeinStore: new MemorySkeinStore(), checkpointer: new MemorySaver() };
+      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_URL", "redis");
+        const redisUrl = requireEnv("REDIS_URI", "redis");
         const redisQueue = new RedisRunQueue(redisUrl);
         disposers.push(() => redisQueue.dispose());
         const redisBus = new RedisRunEventBus(redisUrl);
@@ -212,7 +233,7 @@ async function buildRuntime(options) {
       deps,
       cors: corsFromHttpConfig(first.config.http),
       reloadGraphs: async () => {
-        reroute((await loadConfig({ configPath, importModule })).graphs);
+        reroute((await loadConfig({ configPath, importModule, staticSchemas: schemas })).graphs);
       },
       dispose: disposeAll
     };
@@ -221,8 +242,20 @@ async function buildRuntime(options) {
     throw error;
   }
 }
+function resolveStoreTtl(raw) {
+  if (!raw) return void 0;
+  const ttl = {};
+  if (typeof raw.default_ttl === "number") ttl.defaultTtl = raw.default_ttl;
+  if (typeof raw.refresh_on_read === "boolean") ttl.refreshOnRead = raw.refresh_on_read;
+  if (typeof raw.sweep_interval_minutes === "number") {
+    ttl.sweepIntervalMinutes = raw.sweep_interval_minutes;
+  }
+  return Object.keys(ttl).length > 0 ? ttl : void 0;
+}
 export {
   RuntimeConfigError,
   buildRuntime,
+  embedRuntimePackage,
+  isCustomFunctionPath,
   resolveEmbed
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/runtime",
-  "version": "0.3.0",
+  "version": "0.5.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.3.0",
-    "@skein-js/express": "0.3.0",
-    "@skein-js/config": "0.3.0",
-    "@skein-js/storage-memory": "0.3.0",
-    "@skein-js/storage-postgres": "0.3.0",
-    "@skein-js/redis": "0.3.0"
+    "@skein-js/agent-protocol": "0.5.0",
+    "@skein-js/express": "0.5.0",
+    "@skein-js/config": "0.5.0",
+    "@skein-js/redis": "0.5.0",
+    "@skein-js/storage-memory": "0.5.0",
+    "@skein-js/storage-postgres": "0.5.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.3.0"
+    "@skein-js/test-support": "0.5.0"
   },
   "publishConfig": {
     "access": "public"