llm-agent-runtime 0.1.6 → 0.1.17

package/dist/agent.d.ts

@@ -13,7 +13,8 @@ export type AgentFactory = {
 };
 export declare function createAgentFactory(options: {
     llm: BaseChatModel;
-    intentRegistry: IntentRegistry;
+    /** Tools only — context typing is owned by prompts / createAgentRuntime. */
+    intentRegistry: IntentRegistry<any>;
     redisUrl?: string;
     checkpointer?: BaseCheckpointSaver;
 }): Promise<AgentFactory>;

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AACjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,MAAM,YAAY,GAAG;IACzB,YAAY,EAAE,mBAAmB,CAAC;IAClC,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;IACxF,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,MAAM,EAAE;YAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;SAAE,CAAA;KAAE,CAAC,CAAC;CACpF,CAAC;AAEF,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,GAAG,EAAE,aAAa,CAAC;IACnB,cAAc,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC,GAAG,OAAO,CAAC,YAAY,CAAC,CAsCxB"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAIjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AACjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,MAAM,YAAY,GAAG;IACzB,YAAY,EAAE,mBAAmB,CAAC;IAClC,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;IACxF,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,MAAM,EAAE;YAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;SAAE,CAAA;KAAE,CAAC,CAAC;CACpF,CAAC;AA4CF,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,GAAG,EAAE,aAAa,CAAC;IACnB,4EAA4E;IAC5E,cAAc,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC,GAAG,OAAO,CAAC,YAAY,CAAC,CAqCxB"}

package/dist/agent.js

@@ -1,11 +1,43 @@
 import { createReactAgent } from "@langchain/langgraph/prebuilt";
 import { MemorySaver } from "@langchain/langgraph-checkpoint";
 import { RedisSaver } from "@langchain/langgraph-checkpoint-redis";
+import { createClient } from "redis";
+/**
+ * RedisSaver needs Redis Stack (RedisJSON + RediSearch).
+ * Plain redis://localhost has neither — probe and fall back to MemorySaver.
+ */
+async function createCheckpointer(redisUrl, existing) {
+    if (existing)
+        return existing;
+    if (!redisUrl)
+        return new MemorySaver();
+    const client = createClient({ url: redisUrl });
+    client.on("error", () => {
+        /* probe client — swallow to avoid process crash */
+    });
+    try {
+        await client.connect();
+        const probeKey = `__llm_agent_runtime_probe_${Date.now()}`;
+        await client.sendCommand(["JSON.SET", probeKey, "$", "{}"]);
+        await client.del(probeKey);
+        await client.quit().catch(() => undefined);
+    }
+    catch {
+        await client.quit().catch(() => undefined);
+        console.warn("[llm-agent-runtime] Redis Stack (RedisJSON) not available — using in-memory checkpointer. " +
+            "Flow cache can still use Redis; install Redis Stack for durable LangGraph checkpoints.");
+        return new MemorySaver();
+    }
+    try {
+        return await RedisSaver.fromUrl(redisUrl);
+    }
+    catch (err) {
+        console.warn("[llm-agent-runtime] RedisSaver.fromUrl failed — using in-memory checkpointer:", err instanceof Error ? err.message : err);
+        return new MemorySaver();
+    }
+}
 export async function createAgentFactory(options) {
-    const checkpointer = options.checkpointer ??
-        (options.redisUrl
-            ? await RedisSaver.fromUrl(options.redisUrl)
-            : new MemorySaver());
+    const checkpointer = await createCheckpointer(options.redisUrl, options.checkpointer);
     const fallbackTools = () => {
         const first = Object.values(options.intentRegistry)[0];
         return first?.tools("") ?? [];

package/dist/create-runtime.d.ts

@@ -1,11 +1,18 @@
-import type { AgentRuntimeConfig, InvokeInput, InvokeResult } from "./types.js";
-export type AgentRuntime = {
-    invoke: (input: InvokeInput) => Promise<InvokeResult>;
+import type { AgentRuntimeConfig, InvokeInput, InvokeResult, TokenUsageReport } from "./types.js";
+export type AgentRuntime<TContext = unknown> = {
+    invoke: (input: InvokeInput<TContext>) => Promise<InvokeResult>;
     connect: () => Promise<void>;
     disconnect: () => Promise<void>;
     clearFlow: (threadId: string) => Promise<void>;
     /** Clears LangGraph checkpoint thread (conversation memory). */
     clearThread: (threadId: string) => Promise<void>;
+    /**
+     * Frontend “clear session”: checkpoint + sticky flow state + token usage.
+     * Same as clearThread + usage wipe.
+     */
+    clearSession: (threadId: string) => Promise<void>;
+    /** Read accumulated token usage for a thread (Redis or memory). */
+    getUsage: (threadId: string) => Promise<TokenUsageReport["total"]>;
     getCachedAnswer: (message: string) => Promise<string | undefined>;
     setCachedAnswer: (message: string, answer: string) => Promise<void>;
     /** Invalidate embedding cache after changing intent examples at runtime. */
@@ -14,6 +21,9 @@ export type AgentRuntime = {
 /**
  * Factory for a reusable agent runtime.
  * Engine pipeline: resolveFlow → runAgent → getTurnMessages → extract → finalize
+ *
+ * Pass your context type so prompts get typed `ctx.context`:
+ * `createAgentRuntime<{ userInfo?: { name?: string } }>({ ... })`
  */
-export declare function createAgentRuntime(config: AgentRuntimeConfig): Promise<AgentRuntime>;
+export declare function createAgentRuntime<TContext = unknown>(config: AgentRuntimeConfig<TContext>): Promise<AgentRuntime<TContext>>;
 //# sourceMappingURL=create-runtime.d.ts.map

package/dist/create-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-runtime.d.ts","sourceRoot":"","sources":["../src/create-runtime.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EACX,YAAY,EAEb,MAAM,YAAY,CAAC;AAepB,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACtD,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,gEAAgE;IAChE,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAClE,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,4EAA4E;IAC5E,0BAA0B,EAAE,MAAM,IAAI,CAAC;CACxC,CAAC;AAEF;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,YAAY,CAAC,CAoPvB"}
+{"version":3,"file":"create-runtime.d.ts","sourceRoot":"","sources":["../src/create-runtime.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EACX,YAAY,EAEZ,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAepB,MAAM,MAAM,YAAY,CAAC,QAAQ,GAAG,OAAO,IAAI;IAC7C,MAAM,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAChE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,gEAAgE;IAChE,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD;;;OAGG;IACH,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,mEAAmE;IACnE,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC;IACnE,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAClE,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,4EAA4E;IAC5E,0BAA0B,EAAE,MAAM,IAAI,CAAC;CACxC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,GAAG,OAAO,EACzD,MAAM,EAAE,kBAAkB,CAAC,QAAQ,CAAC,GACnC,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAwVjC"}

package/dist/create-runtime.js

@@ -10,6 +10,9 @@ import { createCompleteOnFinalize, toolOutputMapToExtractors, } from "./services
 import { createFlowRouter, stickySetFromIntents, } from "./services/flow-router.js";
 import { createIntentEmbeddings } from "./services/intent-embeddings.js";
 import { createIntentRouter } from "./services/intent-router.js";
+import { extractTokenUsageFromMessages } from "./services/token-usage.js";
+import { createUsageStore } from "./services/usage-store.js";
+import { assertInvokeInput } from "./errors.js";
 import { getLastMessageContent } from "./utils/message.js";
 /** Messages for this user turn only (used to extract tool outputs). */
 const getTurnMessages = (allMessages, userMessage) => {
@@ -26,16 +29,34 @@ const getTurnMessages = (allMessages, userMessage) => {
 /**
  * Factory for a reusable agent runtime.
  * Engine pipeline: resolveFlow → runAgent → getTurnMessages → extract → finalize
+ *
+ * Pass your context type so prompts get typed `ctx.context`:
+ * `createAgentRuntime<{ userInfo?: { name?: string } }>({ ... })`
  */
 export async function createAgentRuntime(config) {
-    // Wire LangSmith tracing: auto-detect from env or explicit config
-    const langsmithKey = process.env.LANGSMITH_API_KEY;
-    const tracingEnabled = config.tracing?.enabled ?? !!langsmithKey;
+    // Wire LangSmith tracing before models are created.
+    // Respect LANGSMITH_PROJECT / LANGCHAIN_PROJECT (do not force a package default over env).
+    const langsmithKey = process.env.LANGSMITH_API_KEY?.trim() ||
+        process.env.LANGCHAIN_API_KEY?.trim() ||
+        undefined;
+    const tracingEnabled = config.tracing?.enabled ?? Boolean(langsmithKey);
     if (tracingEnabled) {
-        process.env.LANGCHAIN_TRACING_V2 = "true";
-        if (langsmithKey)
+        if (!langsmithKey) {
+            console.warn("[llm-agent-runtime] tracing.enabled but no LANGSMITH_API_KEY / LANGCHAIN_API_KEY set");
+        }
+        else {
+            const project = config.tracing?.projectName?.trim() ||
+                process.env.LANGSMITH_PROJECT?.trim() ||
+                process.env.LANGCHAIN_PROJECT?.trim() ||
+                "llm-agent-runtime";
+            process.env.LANGCHAIN_TRACING_V2 = "true";
+            process.env.LANGSMITH_TRACING = "true";
             process.env.LANGCHAIN_API_KEY = langsmithKey;
-        process.env.LANGCHAIN_PROJECT = config.tracing?.projectName ?? "llm-agent-runtime";
+            process.env.LANGSMITH_API_KEY = langsmithKey;
+            process.env.LANGCHAIN_PROJECT = project;
+            process.env.LANGSMITH_PROJECT = project;
+            console.log("[llm-agent-runtime] LangSmith tracing on", { project });
+        }
     }
     const defaultIntent = config.defaultIntent ?? config.intents[0]?.name ?? "greetings";
     const intentNames = new Set(config.intents.map((i) => i.name));
@@ -56,6 +77,15 @@ export async function createAgentRuntime(config) {
     const chat = config.models?.chat ?? created.chat;
     const intentRouterModel = config.models?.intentRouter ?? created.intentRouter;
     const embeddings = config.models?.embeddings ?? created.embeddings;
+    console.log("[llm-agent-runtime] models", {
+        provider: created.config.provider,
+        chat: created.config.model,
+        intentRouter: created.config.intentRouterModel,
+        embeddingsProvider: created.config.embeddingsProvider,
+        embeddings: created.config.embeddingsModel,
+        baseUrl: llm.baseUrl,
+        embeddingsBaseUrl: llm.embeddingsBaseUrl,
+    });
     const fromMap = config.toolOutputMap
         ? toolOutputMapToExtractors(config.toolOutputMap)
         : null;
@@ -70,7 +100,7 @@ export async function createAgentRuntime(config) {
                 toolOutputMap: config.toolOutputMap,
             })
             : undefined);
-    // Redis client when redisUrl is set (flow state + optional answer cache)
+    // Redis client when redisUrl is set (flow state + optional answer cache + usage)
     const redis = config.redisUrl
         ? createRedis(config.redisUrl)
         : undefined;
@@ -83,6 +113,10 @@ export async function createAgentRuntime(config) {
             scope: config.cache?.scope,
         },
     });
+    const usageStore = createUsageStore({
+        redis: redis?.client,
+        ttlSeconds: config.cache?.ttlSeconds ?? 60 * 60 * 24 * 7,
+    });
     const agentFactory = await createAgentFactory({
         llm: chat,
         intentRegistry: config.intentRegistry,
@@ -127,21 +161,44 @@ export async function createAgentRuntime(config) {
                 includeUnknown: config.includeUnknownToolOutputs ?? false,
             })
             : extractRawToolOutputs);
+    const resolveSharedPrompt = (ctx) => {
+        const shared = config.sharedPrompt;
+        if (!shared)
+            return "";
+        return typeof shared === "function" ? shared(ctx) : shared;
+    };
+    const buildIntentPrompt = (ctx) => {
+        const binding = config.intentRegistry[ctx.intent];
+        if (!binding) {
+            const fallback = Object.values(config.intentRegistry)[0];
+            return fallback?.prompt(ctx) ?? "";
+        }
+        return binding.prompt(ctx);
+    };
     const buildSystemPrompt = config.buildSystemPrompt ??
         ((ctx) => {
-            const binding = config.intentRegistry[ctx.intent];
-            if (!binding) {
-                const fallback = Object.values(config.intentRegistry)[0];
-                return fallback?.prompt(ctx) ?? "";
-            }
-            return binding.prompt(ctx);
+            const shared = resolveSharedPrompt(ctx).trim();
+            const intentPrompt = buildIntentPrompt(ctx).trim();
+            if (shared && intentPrompt)
+                return `${shared}\n\n${intentPrompt}`;
+            return shared || intentPrompt;
         });
     const resolvePhoneKey = config.resolvePhoneKey ??
         (({ threadId, phoneKey }) => phoneKey ?? threadId);
+    const clearSession = async (threadId) => {
+        const saver = agentFactory.checkpointer;
+        if (typeof saver.deleteThread === "function") {
+            await saver.deleteThread(threadId);
+        }
+        await chatCache.clearChatCacheFlowState(threadId);
+        await usageStore.clearThreadUsage(threadId);
+    };
     const invoke = async (input) => {
+        assertInvokeInput(input);
         if (chatCache.enabled) {
             const cached = await chatCache.getCachedAnswer(input.message);
             if (cached) {
+                const total = await usageStore.getThreadUsage(input.threadId);
                 return {
                     messages: [],
                     answer: cached,
@@ -150,6 +207,16 @@ export async function createAgentRuntime(config) {
                     toolOutputs: {},
                     flowCompleted: false,
                     extras: { cacheHit: true },
+                    usage: {
+                        turn: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
+                        flow: {
+                            inputTokens: 0,
+                            outputTokens: 0,
+                            totalTokens: 0,
+                            intent: null,
+                        },
+                        total,
+                    },
                 };
             }
         }
@@ -197,6 +264,30 @@ export async function createAgentRuntime(config) {
         if (chatCache.enabled && answer) {
             await chatCache.setCachedAnswer(input.message, answer);
         }
+        // Token usage: this turn + sticky-flow bucket + thread total (Redis when set)
+        const turnUsage = extractTokenUsageFromMessages(turnMessages);
+        const flowIntentForUsage = finalized.flow.active && finalized.flow.intent
+            ? finalized.flow.intent
+            : stickyFlows.has(promptIntent)
+                ? promptIntent
+                : null;
+        const { total, flow: flowUsage } = await usageStore.recordTurn({
+            threadId: input.threadId,
+            flowIntent: flowIntentForUsage,
+            turn: turnUsage,
+        });
+        if (finalized.flowCompleted && flowIntentForUsage) {
+            // Keep completed-flow totals in this response; reset bucket for next flow
+            await usageStore.clearFlowUsage(input.threadId, flowIntentForUsage);
+        }
+        const usage = {
+            turn: turnUsage,
+            flow: {
+                ...flowUsage,
+                intent: flowIntentForUsage,
+            },
+            total,
+        };
         return {
             messages: resultMessages,
             answer,
@@ -205,6 +296,7 @@ export async function createAgentRuntime(config) {
             toolOutputs,
             flowCompleted: finalized.flowCompleted,
             extras: finalized.extras,
+            usage,
             ...(llmResult
                 ? { router: { action: llmResult.action, reason: llmResult.reason } }
                 : {}),
@@ -219,13 +311,9 @@ export async function createAgentRuntime(config) {
             await redis?.disconnect();
         },
         clearFlow: chatCache.clearChatCacheFlowState,
-        clearThread: async (threadId) => {
-            const saver = agentFactory.checkpointer;
-            if (typeof saver.deleteThread === "function") {
-                await saver.deleteThread(threadId);
-            }
-            await chatCache.clearChatCacheFlowState(threadId);
-        },
+        clearThread: clearSession,
+        clearSession,
+        getUsage: usageStore.getThreadUsage,
         getCachedAnswer: chatCache.getCachedAnswer,
         setCachedAnswer: chatCache.setCachedAnswer,
         invalidateIntentEmbeddings: intentEmbeddings.invalidate,

package/dist/embeddings/xenova.d.ts

@@ -0,0 +1,19 @@
+import { Embeddings, type EmbeddingsParams } from "@langchain/core/embeddings";
+export type XenovaEmbeddingsParams = EmbeddingsParams & {
+    /** Hugging Face / Xenova model id. Default: Xenova/all-MiniLM-L6-v2 */
+    model?: string;
+};
+/**
+ * Free, in-process embeddings via `@xenova/transformers` (no Ollama / OpenAI).
+ * Install: `pnpm add @xenova/transformers`
+ */
+export declare class XenovaEmbeddings extends Embeddings {
+    model: string;
+    private pipelinePromise;
+    constructor(fields?: XenovaEmbeddingsParams);
+    private getPipeline;
+    private toVector;
+    embedDocuments(documents: string[]): Promise<number[][]>;
+    embedQuery(document: string): Promise<number[]>;
+}
+//# sourceMappingURL=xenova.d.ts.map

package/dist/embeddings/xenova.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xenova.d.ts","sourceRoot":"","sources":["../../src/embeddings/xenova.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAoD/E,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,GAAG;IACtD,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,UAAU;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,eAAe,CAAmD;gBAE9D,MAAM,CAAC,EAAE,sBAAsB;YAK7B,WAAW;IAUzB,OAAO,CAAC,QAAQ;IAQV,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAUxD,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAItD"}

package/dist/embeddings/xenova.js

@@ -0,0 +1,69 @@
+import { Embeddings } from "@langchain/core/embeddings";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+async function loadXenovaTransformers() {
+    const errors = [];
+    try {
+        return (await import("@xenova/transformers"));
+    }
+    catch (err) {
+        errors.push(`package import: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // pnpm nests this package; resolve from the app's node_modules / cwd.
+    try {
+        const requireFromCwd = createRequire(path.join(process.cwd(), "package.json"));
+        const resolved = requireFromCwd.resolve("@xenova/transformers");
+        return (await import(pathToFileURL(resolved).href));
+    }
+    catch (err) {
+        errors.push(`cwd resolve: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    throw new Error([
+        'embeddingsProvider "xenova" could not load @xenova/transformers.',
+        "Install in your app: pnpm add @xenova/transformers",
+        "If you see a sharp error, rebuild native deps: pnpm rebuild sharp --config.ignore-scripts=false",
+        ...errors.map((e) => `  - ${e.split("\n")[0]}`),
+    ].join("\n"));
+}
+/**
+ * Free, in-process embeddings via `@xenova/transformers` (no Ollama / OpenAI).
+ * Install: `pnpm add @xenova/transformers`
+ */
+export class XenovaEmbeddings extends Embeddings {
+    model;
+    pipelinePromise = null;
+    constructor(fields) {
+        super(fields ?? {});
+        this.model = fields?.model ?? "Xenova/all-MiniLM-L6-v2";
+    }
+    async getPipeline() {
+        if (!this.pipelinePromise) {
+            this.pipelinePromise = (async () => {
+                const mod = await loadXenovaTransformers();
+                return mod.pipeline("feature-extraction", this.model);
+            })();
+        }
+        return this.pipelinePromise;
+    }
+    toVector(result) {
+        if (typeof result.tolist === "function") {
+            const list = result.tolist();
+            return Array.isArray(list[0]) ? list[0] : list;
+        }
+        return Array.from(result.data);
+    }
+    async embedDocuments(documents) {
+        const pipe = await this.getPipeline();
+        const vectors = [];
+        for (const doc of documents) {
+            const result = await pipe(doc, { pooling: "mean", normalize: true });
+            vectors.push(this.toVector(result));
+        }
+        return vectors;
+    }
+    async embedQuery(document) {
+        const [vector] = await this.embedDocuments([document]);
+        return vector ?? [];
+    }
+}

package/dist/env-llm.d.ts

@@ -1,12 +1,25 @@
-import type { LlmConfig } from "./types.js";
+import type { EmbeddingsProvider, LlmConfig, LlmProvider } from "./types.js";
+/** Vercel / Lambda / Netlify — @xenova/transformers + sharp do not work here. */
+export declare function isServerlessRuntime(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Resolve embeddings backend.
+ *
+ * - Explicit EMBEDDINGS_PROVIDER wins (ollama | openai | xenova), except:
+ *   on serverless (Vercel/Lambda/…) with OPENAI_API_KEY, xenova → openai
+ *   (Transformers.js / sharp cannot load in those runtimes).
+ * - openrouter is not an embeddings backend → xenova locally, openai on serverless+key.
+ * - If unset: ollama chat → ollama; serverless+OPENAI_API_KEY → openai; else → xenova.
+ */
+export declare function resolveEmbeddingsProvider(env: NodeJS.ProcessEnv, chatProvider: LlmProvider): EmbeddingsProvider;
 /**
  * Build LlmConfig from process.env.
  *
  * Env knobs:
- * - LLM_PROVIDER / EMBEDDINGS_PROVIDER — ollama | openai | openrouter
+ * - LLM_PROVIDER — ollama | openai | openrouter
+ * - EMBEDDINGS_PROVIDER — ollama | openai | xenova
+ *   (default: ollama if LLM is ollama; openai on Vercel/Lambda when OPENAI_API_KEY set; else xenova)
  * - OLLAMA_MODEL / OPENAI_MODEL / OPENROUTER_MODEL
- * - INTENT_ROUTER_MODEL / OPENAI_INTENT_ROUTER_MODEL / OPENROUTER_INTENT_ROUTER_MODEL
- * - OLLAMA_EMBEDDINGS_MODEL / OPENAI_EMBEDDINGS_MODEL
+ * - XENOVA_EMBEDDINGS_MODEL / OLLAMA_EMBEDDINGS_MODEL / OPENAI_EMBEDDINGS_MODEL
  * - OLLAMA_BASE_URL / OPENAI_API_KEY / OPENROUTER_API_KEY / OPENROUTER_BASE_URL
  */
 export declare function llmConfigFromEnv(env?: NodeJS.ProcessEnv): LlmConfig;

package/dist/env-llm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env-llm.d.ts","sourceRoot":"","sources":["../src/env-llm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAqBzD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,SAAS,CAiDX"}
+{"version":3,"file":"env-llm.d.ts","sourceRoot":"","sources":["../src/env-llm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAqB7E,iFAAiF;AACjF,wBAAgB,mBAAmB,CACjC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAQT;AAMD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,YAAY,EAAE,WAAW,GACxB,kBAAkB,CAuBpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,SAAS,CAuDX"}

package/dist/env-llm.js

@@ -1,45 +1,95 @@
-const asProvider = (value, fallback) => {
+const asChatProvider = (value, fallback) => {
     const normalized = value?.trim().toLowerCase();
     if (normalized === "openai" ||
         normalized === "gpt" ||
         normalized === "chatgpt") {
         return "openai";
     }
-    if (normalized === "openrouter" ||
-        normalized === "or") {
+    if (normalized === "openrouter" || normalized === "or") {
         return "openrouter";
     }
     if (normalized === "ollama")
         return "ollama";
     return fallback;
 };
+/** Vercel / Lambda / Netlify — @xenova/transformers + sharp do not work here. */
+export function isServerlessRuntime(env = process.env) {
+    return Boolean(env.VERCEL ||
+        env.VERCEL_ENV ||
+        env.AWS_LAMBDA_FUNCTION_NAME ||
+        env.NETLIFY ||
+        env.NETLIFY_DEV);
+}
+function preferOpenAiOnServerless(env) {
+    return isServerlessRuntime(env) && Boolean(env.OPENAI_API_KEY?.trim());
+}
+/**
+ * Resolve embeddings backend.
+ *
+ * - Explicit EMBEDDINGS_PROVIDER wins (ollama | openai | xenova), except:
+ *   on serverless (Vercel/Lambda/…) with OPENAI_API_KEY, xenova → openai
+ *   (Transformers.js / sharp cannot load in those runtimes).
+ * - openrouter is not an embeddings backend → xenova locally, openai on serverless+key.
+ * - If unset: ollama chat → ollama; serverless+OPENAI_API_KEY → openai; else → xenova.
+ */
+export function resolveEmbeddingsProvider(env, chatProvider) {
+    const raw = env.EMBEDDINGS_PROVIDER?.trim().toLowerCase();
+    const serverlessOpenAi = preferOpenAiOnServerless(env);
+    if (raw === "openai" || raw === "gpt" || raw === "chatgpt")
+        return "openai";
+    if (raw === "ollama")
+        return "ollama";
+    if (raw === "xenova" ||
+        raw === "transformers" ||
+        raw === "local" ||
+        raw === "minilm") {
+        return serverlessOpenAi ? "openai" : "xenova";
+    }
+    // OpenRouter has chat only — not an embeddings API.
+    if (raw === "openrouter" || raw === "or") {
+        return serverlessOpenAi ? "openai" : "xenova";
+    }
+    // Unset / unknown
+    if (chatProvider === "ollama")
+        return "ollama";
+    if (serverlessOpenAi)
+        return "openai";
+    return "xenova";
+}
 /**
  * Build LlmConfig from process.env.
  *
  * Env knobs:
- * - LLM_PROVIDER / EMBEDDINGS_PROVIDER — ollama | openai | openrouter
+ * - LLM_PROVIDER — ollama | openai | openrouter
+ * - EMBEDDINGS_PROVIDER — ollama | openai | xenova
+ *   (default: ollama if LLM is ollama; openai on Vercel/Lambda when OPENAI_API_KEY set; else xenova)
  * - OLLAMA_MODEL / OPENAI_MODEL / OPENROUTER_MODEL
- * - INTENT_ROUTER_MODEL / OPENAI_INTENT_ROUTER_MODEL / OPENROUTER_INTENT_ROUTER_MODEL
- * - OLLAMA_EMBEDDINGS_MODEL / OPENAI_EMBEDDINGS_MODEL
+ * - XENOVA_EMBEDDINGS_MODEL / OLLAMA_EMBEDDINGS_MODEL / OPENAI_EMBEDDINGS_MODEL
  * - OLLAMA_BASE_URL / OPENAI_API_KEY / OPENROUTER_API_KEY / OPENROUTER_BASE_URL
  */
 export function llmConfigFromEnv(env = process.env) {
-    const provider = asProvider(env.LLM_PROVIDER, "ollama");
-    const embeddingsProvider = asProvider(env.EMBEDDINGS_PROVIDER ?? env.LLM_PROVIDER, provider);
+    const provider = asChatProvider(env.LLM_PROVIDER, "ollama");
+    const embeddingsProvider = resolveEmbeddingsProvider(env, provider);
     const openrouterBaseUrl = env.OPENROUTER_BASE_URL ?? "https://openrouter.ai/api/v1";
+    const ollamaBaseUrl = env.OLLAMA_BASE_URL ?? "http://localhost:11434";
+    const resolvedEmbeddingsModel = embeddingsProvider === "openai"
+        ? (env.OPENAI_EMBEDDINGS_MODEL ?? "text-embedding-3-small")
+        : embeddingsProvider === "xenova"
+            ? (env.XENOVA_EMBEDDINGS_MODEL ?? "Xenova/all-MiniLM-L6-v2")
+            : (env.OLLAMA_EMBEDDINGS_MODEL ?? "mxbai-embed-large:latest");
     if (provider === "openrouter") {
         return {
             provider,
-            embeddingsProvider: embeddingsProvider === "openrouter" ? "ollama" : embeddingsProvider,
+            embeddingsProvider,
             model: env.OPENROUTER_MODEL ?? "meta-llama/llama-4-scout",
             intentRouterModel: env.OPENROUTER_INTENT_ROUTER_MODEL ??
                 env.OPENROUTER_MODEL ??
                 "meta-llama/llama-4-scout",
-            embeddingsModel: embeddingsProvider === "openai"
-                ? (env.OPENAI_EMBEDDINGS_MODEL ?? "text-embedding-3-small")
-                : (env.OLLAMA_EMBEDDINGS_MODEL ?? "mxbai-embed-large:latest"),
+            embeddingsModel: resolvedEmbeddingsModel,
             baseUrl: openrouterBaseUrl,
+            embeddingsBaseUrl: embeddingsProvider === "ollama" ? ollamaBaseUrl : undefined,
             apiKey: env.OPENROUTER_API_KEY,
+            embeddingsApiKey: env.OPENAI_API_KEY,
         };
     }
     return {
@@ -55,10 +105,10 @@ export function llmConfigFromEnv(env = process.env) {
             : (env.INTENT_ROUTER_MODEL ??
                 env.OLLAMA_INTENT_ROUTER_MODEL ??
                 "qwen2.5:7b"),
-        embeddingsModel: embeddingsProvider === "openai"
-            ? (env.OPENAI_EMBEDDINGS_MODEL ?? "text-embedding-3-small")
-            : (env.OLLAMA_EMBEDDINGS_MODEL ?? "mxbai-embed-large:latest"),
-        baseUrl: env.OLLAMA_BASE_URL,
+        embeddingsModel: resolvedEmbeddingsModel,
+        baseUrl: provider === "openai" ? undefined : ollamaBaseUrl,
+        embeddingsBaseUrl: embeddingsProvider === "ollama" ? ollamaBaseUrl : undefined,
         apiKey: env.OPENAI_API_KEY,
+        embeddingsApiKey: env.OPENAI_API_KEY,
     };
 }

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+/** Thrown when `invoke` input fails validation (e.g. missing threadId). */
+export declare class AgentRuntimeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function assertInvokeInput(input: {
+    message?: unknown;
+    threadId?: unknown;
+}): void;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,IAAI,CAaP"}

package/dist/errors.js

@@ -0,0 +1,17 @@
+/** Thrown when `invoke` input fails validation (e.g. missing threadId). */
+export class AgentRuntimeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "AgentRuntimeError";
+        this.code = code;
+    }
+}
+export function assertInvokeInput(input) {
+    if (typeof input.message !== "string" || !input.message.trim()) {
+        throw new AgentRuntimeError("INVALID_MESSAGE", 'invoke() requires a non-empty string "message".');
+    }
+    if (typeof input.threadId !== "string" || !input.threadId.trim()) {
+        throw new AgentRuntimeError("MISSING_THREAD_ID", 'invoke() requires a non-empty string "threadId" so the checkpointer can persist conversation state. Example: runtime.invoke({ message, threadId: "user-123" })');
+    }
+}

package/dist/index.d.ts

@@ -1,11 +1,20 @@
 export { createAgentRuntime, type AgentRuntime } from "./create-runtime.js";
 export { createModels } from "./llm.js";
-export { llmConfigFromEnv } from "./env-llm.js";
+export { llmConfigFromEnv, resolveEmbeddingsProvider, isServerlessRuntime, } from "./env-llm.js";
 export { createRedis } from "./redis.js";
+export { XenovaEmbeddings } from "./embeddings/xenova.js";
+export { AgentRuntimeError, assertInvokeInput } from "./errors.js";
+export { GENERAL_INTENT_NAME, createGeneralIntent, createGeneralIntentBinding, withGeneralIntent, } from "./intents/general.js";
+export type { WithGeneralIntentOptions } from "./intents/general.js";
+export { defineIntents, withGeneralIntents } from "./intents/define.js";
+export type { UnifiedIntent } from "./intents/define.js";
+export { ragSourcesFromEnv, resolveRagSource, resolveRagSources, isHttpUrl, loadRagDocument, loadRagDocuments, createSimpleRagStore, createSimpleRagFromSources, createSimpleRagFromEnv, getRagStore, getRagDocumentCount, resetRagStore, } from "./rag/index.js";
+export type { RagSourceKind, ResolvedRagSource, LoadedRagDocument, RagChunk, SimpleRagStore, GetRagStoreOptions, } from "./rag/index.js";
 export { extractRawToolOutputs, extractToolCallArgs, getToolCallsFromMessages, createToolOutputExtractor, } from "./services/extract.js";
 export { toolOutputMapToExtractors, createCompleteOnFinalize, } from "./services/simple-config.js";
+export { extractTokenUsageFromMessages, emptyTokenCounts, addTokenCounts, } from "./services/token-usage.js";
 export { isWizardInput } from "./services/flow-router.js";
 export { getLastMessageContent } from "./utils/message.js";
 export { normalize } from "./utils/normalize.js";
-export type { AgentRuntimeConfig, CacheConfig, ChatFlowState, DetectedIntentResult, FinalizeFlowInput, FinalizeFlowResult, FlowResolution, FlowState, IntentBinding, IntentDefinition, IntentRegistry, InvokeInput, InvokeResult, LlmConfig, LlmIntentResult, LlmProvider, PromptContext, ToolCall, ToolExtractor, ToolExtractorMap, ToolOutputMap, TracingConfig, } from "./types.js";
+export type { AgentRuntimeConfig, CacheConfig, ChatFlowState, DetectedIntentResult, EmbeddingsProvider, FinalizeFlowInput, FinalizeFlowResult, FlowResolution, FlowState, FlowTokenUsage, IntentBinding, IntentDefinition, IntentRegistry, InvokeInput, InvokeResult, LlmConfig, LlmIntentResult, LlmProvider, PromptContext, TokenCounts, TokenUsageReport, ToolCall, ToolExtractor, ToolExtractorMap, ToolOutputMap, TracingConfig, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD,YAAY,EACV,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,YAAY,EACZ,SAAS,EACT,eAAe,EACf,WAAW,EACX,aAAa,EACb,QAAQ,EACR,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,aAAa,GACd,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,0BAA0B,EAC1B,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACxE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,sBAAsB,EACtB,WAAW,EACX,mBAAmB,EACnB,aAAa,GACd,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,QAAQ,EACR,cAAc,EACd,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,6BAA6B,EAC7B,gBAAgB,EAChB,cAAc,GACf,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD,YAAY,EACV,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,SAAS,EACT,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,YAAY,EACZ,SAAS,EACT,eAAe,EACf,WAAW,EACX,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,QAAQ,EACR,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,aAAa,GACd,MAAM,YAAY,CAAC"}