@diegoaltoworks/chatter 0.30.0 → 0.32.0

package/dist/flows/__fixtures__/broken/handler.d.ts

@@ -0,0 +1,3 @@
+import type { FlowHandler } from "../../types";
+export declare const execute: FlowHandler;
+//# sourceMappingURL=handler.d.ts.map

package/dist/flows/__fixtures__/broken/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../src/flows/__fixtures__/broken/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,eAAO,MAAM,OAAO,EAAE,WAErB,CAAC"}

package/dist/flows/__fixtures__/greeting/handler.d.ts

@@ -0,0 +1,3 @@
+import type { FlowHandler } from "../../types";
+export declare const execute: FlowHandler;
+//# sourceMappingURL=handler.d.ts.map

package/dist/flows/__fixtures__/greeting/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../src/flows/__fixtures__/greeting/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,eAAO,MAAM,OAAO,EAAE,WAMrB,CAAC"}

package/dist/flows/__fixtures__/greeting/prefill.d.ts

@@ -0,0 +1,3 @@
+import type { FlowPrefill } from "../../types";
+export declare const prefillFromContext: FlowPrefill;
+//# sourceMappingURL=prefill.d.ts.map

package/dist/flows/__fixtures__/greeting/prefill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefill.d.ts","sourceRoot":"","sources":["../../../../src/flows/__fixtures__/greeting/prefill.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,eAAO,MAAM,kBAAkB,EAAE,WAEhC,CAAC"}

package/dist/flows/engine.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Flow engine — orchestrates the flow lifecycle: triggering, multi-turn
+ * parameter collection, execution and cancellation. Channel-agnostic: it
+ * takes a caller-chosen `sessionKey` and returns structured results, never
+ * channel-specific presentation (see {@link FlowHandlerResult}).
+ */
+import type OpenAI from "openai";
+import type { FlowResult, FlowSessionStore, LoadedFlow } from "./types";
+export interface FlowEngineOptions {
+    /** OpenAI client used for intent detection and parameter extraction. */
+    client: OpenAI;
+    /** Model for both LLM calls. */
+    model: string;
+    /** Directory containing flow subdirectories (flow.json/handler.ts/instructions.md). */
+    flowsDir: string;
+    /** Session persistence — see `./session` for the shipped Turso-backed store. */
+    sessionStore: FlowSessionStore;
+    /**
+     * Keyword -> flow id map checked before LLM intent detection. Unset
+     * disables the keyword-trigger step entirely (LLM detection only).
+     */
+    criticalKeywords?: Record<string, string>;
+    /** Confidence threshold an LLM detection must clear to trigger a flow. Default 0.7. */
+    minConfidence?: number;
+    /** Phrases that cancel an active flow. Default: cancel/nevermind/stop/"forget it"/quit. */
+    cancelKeywords?: string[];
+    /** Message returned when a flow is cancelled. */
+    cancelMessage?: string;
+    /** Message returned when flow processing errors out. */
+    errorMessage?: string;
+    /**
+     * How long an inactive session may sit before it's treated as abandoned
+     * and dropped rather than resumed. Unset: sessions never expire on their
+     * own (only completion or a cancel keyword clears one).
+     */
+    sessionTtlMs?: number;
+    /** Clock, injectable for deterministic tests. */
+    now?: () => number;
+}
+export interface FlowEngine {
+    /** Loads (or reloads) every flow directory under `flowsDir`. */
+    loadFlows(): Promise<void>;
+    getFlow(id: string): LoadedFlow | undefined;
+    getAllFlows(): LoadedFlow[];
+    /** Advances (or starts) the flow for `sessionKey` given the caller's latest message. */
+    process(sessionKey: string, message: string, options?: {
+        conversationContext?: string[];
+        channel?: string;
+        /** Passed through to a freshly-triggered flow's `prefill`, when it has one. */
+        prefillContext?: Record<string, unknown>;
+    }): Promise<FlowResult>;
+}
+export declare function createFlowEngine(options: FlowEngineOptions): FlowEngine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/flows/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/flows/engine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAKjC,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGxE,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,uFAAuF;IACvF,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,YAAY,EAAE,gBAAgB,CAAC;IAC/B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,uFAAuF;IACvF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2FAA2F;IAC3F,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iDAAiD;IACjD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAC5C,WAAW,IAAI,UAAU,EAAE,CAAC;IAC5B,wFAAwF;IACxF,OAAO,CACL,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;QAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,+EAA+E;QAC/E,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC1C,GACA,OAAO,CAAC,UAAU,CAAC,CAAC;CACxB;AAMD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAkKvE"}

package/dist/flows/engine.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Flow engine tests — the full processFlow-equivalent lifecycle: triggering,
+ * multi-turn param collection, completion, cancellation and error handling.
+ * Uses a faked OpenAI client (never a real API call) and an in-memory
+ * FlowSessionStore standing in for the Turso-backed one, which has its own
+ * dedicated tests in session.test.ts.
+ */
+export {};
+//# sourceMappingURL=engine.test.d.ts.map

package/dist/flows/engine.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.test.d.ts","sourceRoot":"","sources":["../../src/flows/engine.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/flows/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Flow engine — directory-loaded, schema-driven slot-filling flows with
+ * hybrid (keyword + LLM) intent matching and multi-instance-safe session
+ * state. Published as the `@diegoaltoworks/chatter/flows` subpath so the
+ * core install stays untouched by it.
+ *
+ * Presentation stays out: `process()` returns a structured {@link FlowResult}
+ * ({@link FlowHandlerResult.message} plus an optional `result` payload) —
+ * rendering it for voice, SMS, WhatsApp or anything else is the calling
+ * plugin's job. This module is the designated future home for graph-based
+ * orchestration.
+ *
+ * @packageDocumentation
+ */
+export type { FlowEngine, FlowEngineOptions } from "./engine";
+export { createFlowEngine } from "./engine";
+export { detectIntent } from "./intent";
+export { loadFlowsFromDirectory } from "./loader";
+export { extractParameters } from "./params";
+export type { FlowRegistry } from "./registry";
+export { createFlowRegistry } from "./registry";
+export { createTursoFlowSessionStore } from "./session";
+export type { FlowDefinition, FlowExtractionResult, FlowHandler, FlowHandlerContext, FlowHandlerResult, FlowPrefill, FlowResult, FlowSchema, FlowSchemaProperty, FlowSessionState, FlowSessionStore, IntentDetection, LoadedFlow, } from "./types";
+export { shouldExitFlow } from "./utils";
+//# sourceMappingURL=index.d.ts.map

package/dist/flows/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/flows/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,2BAA2B,EAAE,MAAM,WAAW,CAAC;AACxD,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,UAAU,EACV,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,UAAU,GACX,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC"}

package/dist/flows/index.js

@@ -0,0 +1,481 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/flows/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createFlowEngine: () => createFlowEngine,
+  createFlowRegistry: () => createFlowRegistry,
+  createTursoFlowSessionStore: () => createTursoFlowSessionStore,
+  detectIntent: () => detectIntent,
+  extractParameters: () => extractParameters,
+  loadFlowsFromDirectory: () => loadFlowsFromDirectory,
+  shouldExitFlow: () => shouldExitFlow
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/flows/intent.ts
+async function detectIntent(client, model, message, flows, conversationContext) {
+  const contextStr = conversationContext && conversationContext.length > 0 ? `
+
+Recent conversation:
+${conversationContext.join("\n")}` : "";
+  const flowDescriptions = Array.from(flows.entries()).map(([id, flow], index) => {
+    const keywords = flow.definition.triggerKeywords.join(", ");
+    return `${index + 1}. ${id} -- ${flow.definition.description}
+   - Keywords: ${keywords}`;
+  }).join("\n\n");
+  const systemPrompt = `You are an intent detector.
+
+Detect ONE category. Use these EXACT ids (they must match flow ids):
+
+${flowDescriptions}
+
+${flows.size + 1}. chatbot -- All other questions (general fallback)
+${contextStr}
+
+Return JSON with:
+- "intent": one of the ids above (exact string)
+- "confidence": 0.0-1.0 (how certain you are)
+- "reasoning": brief explanation
+
+Rules:
+- If uncertain, always return "chatbot" with low confidence`;
+  try {
+    const response = await client.chat.completions.create({
+      model,
+      temperature: 0.1,
+      response_format: { type: "json_object" },
+      messages: [
+        { role: "system", content: systemPrompt },
+        { role: "user", content: message }
+      ]
+    });
+    const content = response.choices[0]?.message?.content || "{}";
+    const raw = JSON.parse(content);
+    const validFlowIds = new Set(flows.keys());
+    const intent = validFlowIds.has(raw.intent) ? raw.intent : "chatbot";
+    const confidence = typeof raw.confidence === "number" ? raw.confidence : 0;
+    return { intent, confidence, reasoning: raw.reasoning };
+  } catch (error) {
+    console.warn(
+      `[flows] intent detection failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return { intent: "chatbot", confidence: 0, reasoning: "exception, defaulting to chatbot" };
+  }
+}
+
+// src/flows/loader.ts
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+var SKIPPED_DIR_NAMES = /* @__PURE__ */ new Set(["lib", "tests", "registry"]);
+async function loadFlowsFromDirectory(flowsDir) {
+  const flows = /* @__PURE__ */ new Map();
+  if (!(0, import_node_fs.existsSync)(flowsDir)) {
+    console.warn(`[flows] directory does not exist: ${flowsDir}`);
+    return flows;
+  }
+  const flowDirs = (0, import_node_fs.readdirSync)(flowsDir, { withFileTypes: true }).filter((dirent) => dirent.isDirectory()).filter((dirent) => !SKIPPED_DIR_NAMES.has(dirent.name)).map((dirent) => dirent.name);
+  for (const flowName of flowDirs) {
+    try {
+      flows.set(flowName, await loadFlow(flowsDir, flowName));
+    } catch (error) {
+      console.warn(
+        `[flows] failed to load "${flowName}": ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  return flows;
+}
+async function loadFlow(flowsDir, flowName) {
+  const flowPath = (0, import_node_path.resolve)(flowsDir, flowName);
+  const definitionPath = (0, import_node_path.join)(flowPath, "flow.json");
+  const instructionsPath = (0, import_node_path.join)(flowPath, "instructions.md");
+  const handlerPath = (0, import_node_path.join)(flowPath, "handler.ts");
+  if (!(0, import_node_fs.existsSync)(definitionPath)) {
+    throw new Error(`flow.json not found for ${flowName}`);
+  }
+  if (!(0, import_node_fs.existsSync)(instructionsPath)) {
+    throw new Error(`instructions.md not found for ${flowName}`);
+  }
+  if (!(0, import_node_fs.existsSync)(handlerPath)) {
+    throw new Error(`handler.ts not found for ${flowName}`);
+  }
+  const definition = JSON.parse((0, import_node_fs.readFileSync)(definitionPath, "utf-8"));
+  if (definition.id !== flowName) {
+    throw new Error(`Flow id mismatch: ${definition.id} !== ${flowName}`);
+  }
+  if (!definition.triggerKeywords || definition.triggerKeywords.length === 0) {
+    throw new Error(`Flow ${flowName} has no trigger keywords`);
+  }
+  if (!definition.schema || Object.keys(definition.schema.properties ?? {}).length === 0) {
+    throw new Error(`Flow ${flowName} has no schema`);
+  }
+  const handlerModule = await import(handlerPath);
+  const handler = handlerModule.execute;
+  if (typeof handler !== "function") {
+    throw new Error(`Flow ${flowName} handler.ts must export an 'execute' function`);
+  }
+  const prefillPath = (0, import_node_path.join)(flowPath, "prefill.ts");
+  let prefill;
+  if ((0, import_node_fs.existsSync)(prefillPath)) {
+    const prefillModule = await import(prefillPath);
+    if (typeof prefillModule.prefillFromContext === "function") {
+      prefill = prefillModule.prefillFromContext;
+    } else {
+      console.warn(
+        `[flows] "${flowName}" prefill.ts does not export a prefillFromContext function`
+      );
+    }
+  }
+  return { definition, handler, instructionsPath, prefill };
+}
+
+// src/flows/params.ts
+var import_node_fs2 = require("node:fs");
+function isMissing(value) {
+  return value === void 0 || value === null;
+}
+async function extractParameters(client, model, flow, message, existingParams, now = Date.now) {
+  const instructions = (0, import_node_fs2.readFileSync)(flow.instructionsPath, "utf-8");
+  const schema = flow.definition.schema;
+  const properties = schema.properties || {};
+  const required = schema.required || [];
+  const schemaDescription = Object.entries(properties).map(
+    ([key, field]) => `- ${key} (${field.type}${required.includes(key) ? ", required" : ""}): ${field.description || ""}`
+  ).join("\n");
+  const existingParamsStr = Object.keys(existingParams).length > 0 ? `
+
+Already collected:
+${JSON.stringify(existingParams, null, 2)}` : "";
+  const missingFields = required.filter((key) => isMissing(existingParams[key]));
+  const currentlyAsking = missingFields.length > 0 ? missingFields[0] : null;
+  const nowDate = new Date(now());
+  const todayStr = nowDate.toISOString().split("T")[0];
+  const currentYear = nowDate.getFullYear();
+  const currentMonth = nowDate.getMonth() + 1;
+  const nextYear = currentYear + 1;
+  const tomorrow = new Date(nowDate);
+  tomorrow.setDate(tomorrow.getDate() + 1);
+  const tomorrowStr = tomorrow.toISOString().split("T")[0];
+  const dateContext = `
+
+## CRITICAL DATE CONTEXT
+TODAY IS: ${todayStr} (year ${currentYear}, month ${currentMonth})
+
+**DATE EXTRACTION RULES:**
+- "tomorrow" = ${tomorrowStr}
+- Months 1-${currentMonth} = year ${nextYear}
+- Months ${currentMonth + 1}-12 = year ${currentYear}
+- NEVER output a date before ${todayStr}`;
+  const currentFieldHint = currentlyAsking ? `
+
+## IMPORTANT CONTEXT
+We just asked the user for: "${currentlyAsking}"
+If the user's response is a simple value, interpret it as the value for the "${currentlyAsking}" parameter.` : "";
+  const systemPrompt = `${instructions}
+${dateContext}
+
+## Schema
+${schemaDescription}
+${existingParamsStr}
+${currentFieldHint}
+
+## Task
+Extract any parameters from the user's message that match the schema above.
+Return JSON with:
+- "extractedParams": object with any NEW parameters found
+
+Do not compute "allParamsFilled" - the caller recomputes it from the merged params.`;
+  const response = await client.chat.completions.create({
+    model,
+    temperature: 0.2,
+    response_format: { type: "json_object" },
+    messages: [
+      { role: "system", content: systemPrompt },
+      { role: "user", content: message }
+    ]
+  });
+  const content = response.choices[0]?.message?.content || "{}";
+  const result = JSON.parse(content);
+  const extractedParams = Object.fromEntries(
+    Object.entries(result.extractedParams || {}).filter(([, value]) => !isMissing(value))
+  );
+  const mergedParams = { ...existingParams, ...extractedParams };
+  const allParamsFilled = required.every((key) => !isMissing(mergedParams[key]));
+  let nextPrompt;
+  if (!allParamsFilled) {
+    const missingKey = required.find((key) => isMissing(mergedParams[key]));
+    if (missingKey) {
+      nextPrompt = `What is the ${missingKey.replace(/([A-Z])/g, " $1").toLowerCase()}?`;
+    }
+  }
+  return { extractedParams, allParamsFilled, nextPrompt };
+}
+
+// src/flows/registry.ts
+var import_node_fs3 = require("node:fs");
+function createFlowRegistry(flows, criticalKeywords = {}) {
+  const keywordEntries = Object.entries(criticalKeywords);
+  return {
+    getFlow(id) {
+      return flows.get(id);
+    },
+    getAllFlows() {
+      return Array.from(flows.values());
+    },
+    getInstructions(id) {
+      const flow = flows.get(id);
+      if (!flow) {
+        throw new Error(`Flow ${id} not found`);
+      }
+      return (0, import_node_fs3.readFileSync)(flow.instructionsPath, "utf-8");
+    },
+    matchByKeyword(message) {
+      const lowerMessage = message.toLowerCase();
+      for (const [keyword, flowId] of keywordEntries) {
+        if (lowerMessage.includes(keyword.toLowerCase())) {
+          const flow = flows.get(flowId);
+          if (flow) return flow;
+        }
+      }
+      return void 0;
+    }
+  };
+}
+
+// src/flows/utils.ts
+var DEFAULT_CANCEL_KEYWORDS = ["cancel", "nevermind", "never mind", "stop", "forget it", "quit"];
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function containsWholePhrase(message, phrase) {
+  return new RegExp(`(^|\\W)${escapeRegExp(phrase)}($|\\W)`, "i").test(message);
+}
+function shouldExitFlow(message, cancelKeywords = DEFAULT_CANCEL_KEYWORDS) {
+  return cancelKeywords.some((keyword) => containsWholePhrase(message, keyword));
+}
+
+// src/flows/engine.ts
+var DEFAULT_MIN_CONFIDENCE = 0.7;
+var DEFAULT_CANCEL_MESSAGE = "Okay, cancelled.";
+var DEFAULT_ERROR_MESSAGE = "Sorry, something went wrong. Please try again.";
+function createFlowEngine(options) {
+  const {
+    client,
+    model,
+    flowsDir,
+    sessionStore,
+    criticalKeywords,
+    minConfidence = DEFAULT_MIN_CONFIDENCE,
+    cancelKeywords,
+    cancelMessage = DEFAULT_CANCEL_MESSAGE,
+    errorMessage = DEFAULT_ERROR_MESSAGE,
+    sessionTtlMs,
+    now = Date.now
+  } = options;
+  let registry = createFlowRegistry(/* @__PURE__ */ new Map());
+  async function matchFlow(message, conversationContext) {
+    const byKeyword = registry.matchByKeyword(message);
+    if (byKeyword) return byKeyword;
+    const allFlows = registry.getAllFlows();
+    if (allFlows.length === 0) return void 0;
+    const flowMap = new Map(allFlows.map((flow) => [flow.definition.id, flow]));
+    const detection = await detectIntent(client, model, message, flowMap, conversationContext);
+    if (detection.confidence >= minConfidence) {
+      return registry.getFlow(detection.intent);
+    }
+    return void 0;
+  }
+  async function runToCompletionOrPrompt(flow, sessionKey, message, existingParams, attempts, startedAt, channel) {
+    const extraction = await extractParameters(client, model, flow, message, existingParams, now);
+    const mergedParams = { ...existingParams, ...extraction.extractedParams };
+    if (extraction.allParamsFilled) {
+      const result = await flow.handler(mergedParams, { sessionKey, channel });
+      await sessionStore.clear(sessionKey);
+      return {
+        isFlowActive: false,
+        message: result.message,
+        flowCompleted: true,
+        flowSuccess: result.success,
+        result: result.result
+      };
+    }
+    await sessionStore.set(sessionKey, {
+      flowId: flow.definition.id,
+      params: mergedParams,
+      attempts: attempts + 1,
+      startedAt
+    });
+    return {
+      isFlowActive: true,
+      message: extraction.nextPrompt || "Could you provide more details?",
+      flowCompleted: false
+    };
+  }
+  return {
+    async loadFlows() {
+      const flows = await loadFlowsFromDirectory(flowsDir);
+      registry = createFlowRegistry(flows, criticalKeywords);
+    },
+    getFlow(id) {
+      return registry.getFlow(id);
+    },
+    getAllFlows() {
+      return registry.getAllFlows();
+    },
+    async process(sessionKey, message, processOptions) {
+      const channel = processOptions?.channel;
+      let activeSession = await sessionStore.get(sessionKey);
+      if (activeSession && sessionTtlMs !== void 0 && now() - activeSession.startedAt > sessionTtlMs) {
+        await sessionStore.clear(sessionKey);
+        activeSession = null;
+      }
+      if (activeSession && shouldExitFlow(message, cancelKeywords)) {
+        await sessionStore.clear(sessionKey);
+        return {
+          isFlowActive: false,
+          message: cancelMessage,
+          flowCompleted: false,
+          cancelled: true
+        };
+      }
+      if (activeSession) {
+        const flow = registry.getFlow(activeSession.flowId);
+        if (!flow) {
+          await sessionStore.clear(sessionKey);
+          return { isFlowActive: false, message: errorMessage, flowCompleted: false, error: true };
+        }
+        try {
+          return await runToCompletionOrPrompt(
+            flow,
+            sessionKey,
+            message,
+            activeSession.params,
+            activeSession.attempts,
+            activeSession.startedAt,
+            channel
+          );
+        } catch {
+          return { isFlowActive: true, message: errorMessage, flowCompleted: false, error: true };
+        }
+      }
+      const matched = await matchFlow(message, processOptions?.conversationContext);
+      if (!matched) {
+        return { isFlowActive: false, message: "", flowCompleted: false };
+      }
+      try {
+        const globalParams = matched.prefill ? matched.prefill(sessionKey, processOptions?.prefillContext ?? {}) : {};
+        return await runToCompletionOrPrompt(
+          matched,
+          sessionKey,
+          message,
+          globalParams,
+          0,
+          now(),
+          channel
+        );
+      } catch {
+        return { isFlowActive: false, message: errorMessage, flowCompleted: false, error: true };
+      }
+    }
+  };
+}
+
+// src/flows/session.ts
+var schemaReady = /* @__PURE__ */ new WeakMap();
+function ensureSessionSchema(client, tableName) {
+  let perTable = schemaReady.get(client);
+  if (!perTable) {
+    perTable = /* @__PURE__ */ new Map();
+    schemaReady.set(client, perTable);
+  }
+  const tables = perTable;
+  let ready = tables.get(tableName);
+  if (!ready) {
+    ready = client.execute(
+      `CREATE TABLE IF NOT EXISTS ${tableName} (
+          session_key TEXT PRIMARY KEY,
+          flow_id TEXT NOT NULL,
+          params TEXT NOT NULL,
+          attempts INTEGER NOT NULL,
+          started_at INTEGER NOT NULL
+        )`
+    ).catch((error) => {
+      tables.delete(tableName);
+      throw error;
+    });
+    tables.set(tableName, ready);
+  }
+  return ready;
+}
+var VALID_TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function createTursoFlowSessionStore(client, tableName = "flow_sessions") {
+  if (!VALID_TABLE_NAME.test(tableName)) {
+    throw new Error(`Invalid flow session store table name: ${tableName}`);
+  }
+  return {
+    async get(sessionKey) {
+      await ensureSessionSchema(client, tableName);
+      const result = await client.execute({
+        sql: `SELECT flow_id, params, attempts, started_at FROM ${tableName} WHERE session_key = ?`,
+        args: [sessionKey]
+      });
+      const row = result.rows[0];
+      if (!row) return null;
+      return {
+        flowId: String(row.flow_id),
+        params: JSON.parse(String(row.params)),
+        attempts: Number(row.attempts),
+        startedAt: Number(row.started_at)
+      };
+    },
+    async set(sessionKey, state) {
+      await ensureSessionSchema(client, tableName);
+      await client.execute({
+        sql: `INSERT INTO ${tableName} (session_key, flow_id, params, attempts, started_at) VALUES (?, ?, ?, ?, ?)
+              ON CONFLICT(session_key) DO UPDATE SET flow_id = excluded.flow_id, params = excluded.params, attempts = excluded.attempts, started_at = excluded.started_at`,
+        args: [
+          sessionKey,
+          state.flowId,
+          JSON.stringify(state.params),
+          state.attempts,
+          state.startedAt
+        ]
+      });
+    },
+    async clear(sessionKey) {
+      await ensureSessionSchema(client, tableName);
+      await client.execute({
+        sql: `DELETE FROM ${tableName} WHERE session_key = ?`,
+        args: [sessionKey]
+      });
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createFlowEngine,
+  createFlowRegistry,
+  createTursoFlowSessionStore,
+  detectIntent,
+  extractParameters,
+  loadFlowsFromDirectory,
+  shouldExitFlow
+});