@diegoaltoworks/chatter 0.47.0 → 0.48.0

package/dist/channels/whatsapp/router.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Compose N transport-specific message detectors behind ONE gate
+ * resolution per inbound WhatsApp message.
+ *
+ * A host running its own interceptors alongside the normal chat reply —
+ * a voice-note trigger, a fixed-content reaction, an LLM-extraction reply
+ * that replaces the answer — has historically had to re-derive the same
+ * boilerplate per interceptor: resolving own-identity jids off the socket,
+ * the cross-session loop guard, and the allowlist wiring `decideChannelAction`
+ * already owns. Copy-pasted across interceptors, that boilerplate drifts, and
+ * nothing stops a handler meant to run *alongside* the real reply
+ * (`mode: "parallel"`) from being wired with the *replaces the reply*
+ * convention (`mode: "replace"`) instead — silently eating the real answer.
+ *
+ * `createWhatsAppMessageRouter` resolves identity/gating once via
+ * `resolveWaMessage` (the same helper `createWhatsAppInboundHandler` uses),
+ * builds one {@link WaDetectorContext} for every detector, then:
+ *
+ * - fires every matching `"parallel"` detector without awaiting or gating
+ *   the reply path — a rejection is caught and logged, never surfaces as an
+ *   unhandled rejection, and never blocks another detector or the fallback.
+ * - walks `"replace"` detectors in registration order and stops at the
+ *   first whose `test` matches, awaiting its `handle` and skipping the
+ *   fallback entirely; no match runs `fallback` instead.
+ *
+ * The two modes are distinct at the type level (see {@link MessageDetector}):
+ * both `handle` signatures return `Promise<void>`, so there is no
+ * boolean-return convention to confuse between them — reaching `handle` at
+ * all already means "this detector claims the message" for a `"replace"`
+ * detector, or "fire independently" for a `"parallel"` one.
+ *
+ * `fallback` is deliberately typed the same as `onMessage`/`createWhatsAppInboundHandler`'s
+ * return, so an existing single-handler host becomes the router's fallback
+ * with zero adaptation — see docs/channels.md. Note that plugging it in this
+ * way means `resolveWaMessage` runs a second time inside it (once here for
+ * every detector, once more inside the fallback it delegates to) — cheap and
+ * side-effect-idempotent (it re-derives the same values and re-writes the
+ * same registry entry), but real. "Once per message" below is a guarantee
+ * for the detectors, not for whatever the fallback does internally.
+ */
+import type { WAMessage, WASocket } from "@whiskeysockets/baileys";
+import { type Logger } from "../../core/logger";
+import { type ChannelAction, type ChannelMessage, type SessionIdentityRegistry } from "../gates";
+import type { WhatsAppMessageEvent } from "./channel";
+/** Everything a detector needs, already resolved — never a raw Baileys shape to re-derive. */
+export interface WaDetectorContext {
+    event: WhatsAppMessageEvent;
+    sock: WASocket;
+    message: WAMessage;
+    msg: ChannelMessage;
+    /** This session's own identities (phone + LID, normalized). */
+    ownIds: string[];
+    senderId: string;
+    /** The already-extracted, own-mention-stripped text — see `stripOwnMentions`. */
+    text: string;
+    /**
+     * What `decideChannelAction` would do with this message given THIS
+     * router's own `allowedChats`/`mutedChats`/`muteRegex`/`unmuteRegex` —
+     * informational; detectors decide independently via their own `test`.
+     * If `fallback` is `createWhatsAppInboundHandler`, note it keeps its own
+     * private mute set — this `action` will not reflect chats muted there
+     * unless the same mute inputs are also configured on the router.
+     */
+    action: ChannelAction;
+}
+interface DetectorBase {
+    /** Used only in warning logs when a detector throws. */
+    name: string;
+    test: (ctx: WaDetectorContext) => boolean | Promise<boolean>;
+}
+/** Fires independently of every other detector and of the fallback — never stops the reply path, never treated as "handled". */
+export interface ParallelDetector extends DetectorBase {
+    mode: "parallel";
+    handle: (ctx: WaDetectorContext) => Promise<void>;
+}
+/** The first matching `"replace"` detector (in registration order) fully owns the message — its `handle` runs and the fallback is skipped. */
+export interface ReplaceDetector extends DetectorBase {
+    mode: "replace";
+    handle: (ctx: WaDetectorContext) => Promise<void>;
+}
+export type MessageDetector = ParallelDetector | ReplaceDetector;
+export interface WhatsAppMessageRouterConfig {
+    /** Shared across every session and every consumer resolving identity from it — see `resolveWaMessage`. */
+    registry: SessionIdentityRegistry;
+    /** Same meaning as `WhatsAppInboundConfig.allowedChats`: group chats eligible for routing. Empty (default) = every group; has no effect on DMs. Enforced for every detector and the fallback, independently of message text (a caption-less photo/voice note in a non-allowlisted group is dropped too). */
+    allowedChats?: string[];
+    /** Only consulted to compute `WaDetectorContext.action`; the router itself doesn't act on mute state. */
+    mutedChats?: Set<string>;
+    muteRegex?: RegExp;
+    unmuteRegex?: RegExp;
+    /** Checked in the given order for `"replace"`, independently for `"parallel"`. */
+    detectors: MessageDetector[];
+    /**
+     * Runs when no `"replace"` detector matches. Typed identically to
+     * `onMessage`/`createWhatsAppInboundHandler`'s return, so an existing
+     * single-handler host plugs in unchanged.
+     */
+    fallback: (event: WhatsAppMessageEvent) => Promise<void>;
+    /** A throwing/rejecting callback here is itself caught and logged at `warn` — it can never produce an unhandled rejection. */
+    onDetectorError?: (detectorName: string, error: unknown) => void;
+    /** Logger for detector failures. Default: a console logger writing to stderr. */
+    logger?: Logger;
+}
+/** Builds the `onMessage` handler for `createWhatsAppChannel` that fans a raw message out to N detectors — see the module docstring. */
+export declare function createWhatsAppMessageRouter(config: WhatsAppMessageRouterConfig): (event: WhatsAppMessageEvent) => Promise<void>;
+export {};
+//# sourceMappingURL=router.d.ts.map

package/dist/channels/whatsapp/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAuB,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,cAAc,EAEnB,KAAK,uBAAuB,EAC7B,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAGtD,8FAA8F;AAC9F,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,oBAAoB,CAAC;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,SAAS,CAAC;IACnB,GAAG,EAAE,cAAc,CAAC;IACpB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,UAAU,YAAY;IACpB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D;AAED,gIAAgI;AAChI,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED,8IAA8I;AAC9I,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAEjE,MAAM,WAAW,2BAA2B;IAC1C,0GAA0G;IAC1G,QAAQ,EAAE,uBAAuB,CAAC;IAClC,4SAA4S;IAC5S,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,yGAAyG;IACzG,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,8HAA8H;IAC9H,eAAe,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACjE,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAgDD,wIAAwI;AACxI,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,2BAA2B,GAClC,CAAC,KAAK,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,CA4EhD"}

package/dist/core/answer.d.ts

@@ -30,6 +30,8 @@ export interface AnswerFnInput {
     mode: PipelineMode;
     /** Channel-specific sender identity, when the surface knows one */
     sender?: string;
+    /** Stable conversation/thread identifier, when the surface has or generates one */
+    conversationId?: string;
 }
 /**
  * What a brain returns: the answer text, optionally with token usage for
@@ -53,13 +55,14 @@ export interface AnswerOptions {
     messages: PipelineMessage[];
     mode: PipelineMode;
     sender?: string;
+    conversationId?: string;
     temperature?: number;
     model?: string;
 }
 /**
  * Produce one complete answer, from `answerFn` when configured.
  */
-export declare function answerOnce({ answerFn, client, system, messages, mode, sender, temperature, model, }: AnswerOptions): Promise<{
+export declare function answerOnce({ answerFn, client, system, messages, mode, sender, conversationId, temperature, model, }: AnswerOptions): Promise<{
     content: string;
     usage: AnswerUsage;
 }>;
@@ -72,5 +75,5 @@ export declare function answerOnce({ answerFn, client, system, messages, mode, s
  * built-in stream only scrubs each delta, since leakage detection needs text
  * no streamed chunk has yet.
  */
-export declare function answerStream({ answerFn, client, system, messages, mode, sender, temperature, model, }: AnswerOptions): AsyncGenerator<string>;
+export declare function answerStream({ answerFn, client, system, messages, mode, sender, conversationId, temperature, model, }: AnswerOptions): AsyncGenerator<string>;
 //# sourceMappingURL=answer.d.ts.map

package/dist/core/answer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"answer.d.ts","sourceRoot":"","sources":["../../src/core/answer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAGjC,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEhE,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB;AAKD,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,uCAAuC;IACvC,IAAI,EAAE,YAAY,CAAC;IACnB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAA;CAAE,CAAC;AAE/E;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAAC;AAE1F,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAqBD;;GAEG;AACH,wBAAsB,UAAU,CAAC,EAC/B,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,WAAW,EACX,KAAK,GACN,EAAE,aAAa,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC,CAKlE;AAED;;;;;;;;GAQG;AACH,wBAAuB,YAAY,CAAC,EAClC,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,WAAW,EACX,KAAK,GACN,EAAE,aAAa,GAAG,cAAc,CAAC,MAAM,CAAC,CAOxC"}
+{"version":3,"file":"answer.d.ts","sourceRoot":"","sources":["../../src/core/answer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAGjC,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEhE,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB;AAKD,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,uCAAuC;IACvC,IAAI,EAAE,YAAY,CAAC;IACnB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAA;CAAE,CAAC;AAE/E;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAAC;AAE1F,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAqBD;;GAEG;AACH,wBAAsB,UAAU,CAAC,EAC/B,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,cAAc,EACd,WAAW,EACX,KAAK,GACN,EAAE,aAAa,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC,CAKlE;AAED;;;;;;;;GAQG;AACH,wBAAuB,YAAY,CAAC,EAClC,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,cAAc,EACd,WAAW,EACX,KAAK,GACN,EAAE,aAAa,GAAG,cAAc,CAAC,MAAM,CAAC,CAaxC"}

package/dist/core/logger.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Leveled logging seam. The default implementation never writes to stdout —
+ * only stderr — so a host running the stdio MCP transport (which reserves
+ * stdout for the JSON-RPC stream) gets a clean channel by default, and so do
+ * hosts that simply want their own program output on stdout to stay
+ * unpolluted by library logging.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface Logger {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+/**
+ * Console-backed logger. Every level writes via `console.error` (stderr),
+ * gated by `level` (default `"info"`, so `debug` is silent unless a caller
+ * opts in) — see the module docstring for why stdout is never touched.
+ */
+export declare function createConsoleLogger(level?: LogLevel): Logger;
+/** Resolves a caller-supplied logger, falling back to the default console logger. */
+export declare function resolveLogger(logger?: Logger, level?: LogLevel): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/core/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CACjC;AAID;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,GAAE,QAAiB,GAAG,MAAM,CAcpE;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,CAEvE"}

package/dist/core/messages.d.ts

@@ -12,6 +12,14 @@
  * parts, tool calls, objects, numbers) carries no usable text and is skipped.
  */
 import type { PipelineMessage } from "./pipeline";
+/**
+ * Find the most recent user turn in a conversation. Every chat surface needs
+ * this (retrieval query, RAG logging, ...); a shared helper keeps the
+ * "search from the end" behaviour from drifting between copies.
+ */
+export declare function lastUserMessage<T extends {
+    role: string;
+}>(messages: T[]): T | undefined;
 /**
  * Normalize a raw `messages` array to the pipeline format.
  *

package/dist/core/messages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/core/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAWlD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,EAAE,GAAG,IAAI,CA8BxE;AAED,yDAAyD;AACzD,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,eAAe,EAAE,CAAA;CAAE,GACzC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,kBAAkB,CA2BnE"}
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/core/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAWlD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,SAAS,CAExF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,EAAE,GAAG,IAAI,CA8BxE;AAED,yDAAyD;AACzD,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,eAAe,EAAE,CAAA;CAAE,GACzC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,kBAAkB,CA2BnE"}

package/dist/core/pipeline.d.ts

@@ -20,6 +20,8 @@ export interface PreparedChat {
     system: string;
     /** Conversation messages, unchanged */
     messages: PipelineMessage[];
+    /** Raw retrieved chunks, before being folded into `system` — for callers that log or display RAG context alongside the answer */
+    context: string[];
 }
 /**
  * Run retrieval for the latest user message and assemble the system prompt.

package/dist/core/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/core/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAOD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAAC,EAChC,KAAK,EACL,OAAO,EACP,IAAI,EACJ,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,OAAO,GACR,EAAE;IACD,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,YAAY,CAAC;IACtB,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,GAAG,OAAO,CAAC,YAAY,CAAC,CAmBxB"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/core/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,iIAAiI;IACjI,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAOD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAAC,EAChC,KAAK,EACL,OAAO,EACP,IAAI,EACJ,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,OAAO,GACR,EAAE;IACD,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,YAAY,CAAC;IACtB,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,GAAG,OAAO,CAAC,YAAY,CAAC,CAmBxB"}

package/dist/core/retrieval.d.ts

@@ -1,5 +1,6 @@
 import { type Client as LibsqlClient } from "@libsql/client";
 import type OpenAI from "openai";
+import { type Logger } from "./logger";
 /**
  * How a {@link VectorStore} obtains its database connection: either credentials
  * to open its own, or an existing libsql client to reuse.
@@ -11,6 +12,8 @@ import type OpenAI from "openai";
 export type VectorStoreOptions = {
     /** Directory of markdown knowledge files. Default: `./config/knowledge` */
     knowledgeDir?: string;
+    /** Logger for build progress. Default: a console logger writing to stderr. */
+    logger?: Logger;
 } & ({
     /** Turso database URL */
     databaseUrl: string;
@@ -32,6 +35,7 @@ export declare class VectorStore {
      */
     readonly db: LibsqlClient;
     private knowledgeDir;
+    private logger;
     constructor(client: OpenAI, options: VectorStoreOptions);
     build(): Promise<void>;
     private cleanupStaleChunks;

package/dist/core/retrieval.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retrieval.d.ts","sourceRoot":"","sources":["../../src/core/retrieval.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,MAAM,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AA0BjC;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,CACA;IACE,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,KAAK,CAAC;CACxB,GACD;IACE,gFAAgF;IAChF,cAAc,EAAE,YAAY,CAAC;IAC7B,WAAW,CAAC,EAAE,KAAK,CAAC;IACpB,iBAAiB,CAAC,EAAE,KAAK,CAAC;CAC3B,CACJ,CAAC;AAEF,qBAAa,WAAW;IAUpB,OAAO,CAAC,MAAM;IAThB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,OAAO,CAAC,YAAY,CAAS;IAE7B,YACU,MAAM,EAAE,MAAM,EACtB,OAAO,EAAE,kBAAkB,EAS5B;IAGK,KAAK,kBA0FV;YAGa,kBAAkB;IA8BhC,OAAO,CAAC,MAAM,CAAC,MAAM;IAYrB;;;;;;;;;;OAUG;IACG,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,SAAI,EAAE,OAAO,GAAE,MAAM,EAAa,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAwB7E;CACF"}
+{"version":3,"file":"retrieval.d.ts","sourceRoot":"","sources":["../../src/core/retrieval.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,MAAM,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAEjC,OAAO,EAAuB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAyB5D;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,CACA;IACE,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,KAAK,CAAC;CACxB,GACD;IACE,gFAAgF;IAChF,cAAc,EAAE,YAAY,CAAC;IAC7B,WAAW,CAAC,EAAE,KAAK,CAAC;IACpB,iBAAiB,CAAC,EAAE,KAAK,CAAC;CAC3B,CACJ,CAAC;AAEF,qBAAa,WAAW;IAWpB,OAAO,CAAC,MAAM;IAVhB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAS;IAEvB,YACU,MAAM,EAAE,MAAM,EACtB,OAAO,EAAE,kBAAkB,EAU5B;IAGK,KAAK,kBA0FV;YAGa,kBAAkB;IA8BhC,OAAO,CAAC,MAAM,CAAC,MAAM;IAYrB;;;;;;;;;;OAUG;IACG,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,SAAI,EAAE,OAAO,GAAE,MAAM,EAAa,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAwB7E;CACF"}

package/dist/flows/engine.d.ts

@@ -5,6 +5,7 @@
  * channel-specific presentation (see {@link FlowHandlerResult}).
  */
 import type OpenAI from "openai";
+import { type Logger } from "../core/logger";
 import type { FlowResult, FlowSessionStore, LoadedFlow } from "./types";
 export interface FlowEngineOptions {
     /** OpenAI client used for intent detection and parameter extraction. */
@@ -36,6 +37,8 @@ export interface FlowEngineOptions {
     sessionTtlMs?: number;
     /** Clock, injectable for deterministic tests. */
     now?: () => number;
+    /** Logger for load/intent-detection failures. Default: a console logger writing to stderr. */
+    logger?: Logger;
 }
 export interface FlowEngine {
     /** Loads (or reloads) every flow directory under `flowsDir`. */

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

@@ -1 +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"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/flows/engine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,EAAuB,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAKlE,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;IACnB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;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,CA0KvE"}

package/dist/flows/index.d.ts

@@ -21,5 +21,6 @@ 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 { CURRENT_FLOW_CONTRACT_VERSION } from "./types";
 export { shouldExitFlow } from "./utils";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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"}
+{"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,6BAA6B,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC"}

package/dist/flows/index.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/flows/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CURRENT_FLOW_CONTRACT_VERSION: () => CURRENT_FLOW_CONTRACT_VERSION,
   createFlowEngine: () => createFlowEngine,
   createFlowRegistry: () => createFlowRegistry,
   createTursoFlowSessionStore: () => createTursoFlowSessionStore,
@@ -30,8 +31,24 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/core/logger.ts
+var LEVEL_ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
+function createConsoleLogger(level = "info") {
+  const threshold = LEVEL_ORDER[level];
+  const write = (at) => (...args) => {
+    if (LEVEL_ORDER[at] < threshold) return;
+    console.error(`[${at}]`, ...args);
+  };
+  return {
+    debug: write("debug"),
+    info: write("info"),
+    warn: write("warn"),
+    error: write("error")
+  };
+}
+
 // src/flows/intent.ts
-async function detectIntent(client, model, message, flows, conversationContext) {
+async function detectIntent(client, model, message, flows, conversationContext, logger = createConsoleLogger()) {
   const contextStr = conversationContext && conversationContext.length > 0 ? `
 
 Recent conversation:
@@ -74,7 +91,7 @@ Rules:
     const confidence = typeof raw.confidence === "number" ? raw.confidence : 0;
     return { intent, confidence, reasoning: raw.reasoning };
   } catch (error) {
-    console.warn(
+    logger.warn(
       `[flows] intent detection failed: ${error instanceof Error ? error.message : String(error)}`
     );
     return { intent: "chatbot", confidence: 0, reasoning: "exception, defaulting to chatbot" };
@@ -84,68 +101,108 @@ Rules:
 // src/flows/loader.ts
 var import_node_fs = require("node:fs");
 var import_node_path = require("node:path");
+
+// src/flows/types.ts
+var CURRENT_FLOW_CONTRACT_VERSION = 1;
+
+// src/flows/loader.ts
 var SKIPPED_DIR_NAMES = /* @__PURE__ */ new Set(["lib", "tests", "registry"]);
-async function loadFlowsFromDirectory(flowsDir) {
+var MODULE_EXTENSIONS = ["ts", "js", "mjs"];
+async function loadFlowsFromDirectory(flowsDir, logger = createConsoleLogger()) {
   const flows = /* @__PURE__ */ new Map();
   if (!(0, import_node_fs.existsSync)(flowsDir)) {
-    console.warn(`[flows] directory does not exist: ${flowsDir}`);
+    logger.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));
+      flows.set(flowName, await loadFlow(flowsDir, flowName, logger));
     } catch (error) {
-      console.warn(
+      logger.warn(
         `[flows] failed to load "${flowName}": ${error instanceof Error ? error.message : String(error)}`
       );
     }
   }
   return flows;
 }
-async function loadFlow(flowsDir, flowName) {
+function validateFlowDefinition(raw, flowName) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error(`flow.json for "${flowName}" must be a JSON object`);
+  }
+  const definition = raw;
+  if (typeof definition.id !== "string" || definition.id.length === 0) {
+    throw new Error(`flow.json for "${flowName}": "id" must be a non-empty string`);
+  }
+  if (!Array.isArray(definition.triggerKeywords) || definition.triggerKeywords.length === 0) {
+    throw new Error(`flow.json for "${flowName}": "triggerKeywords" must be a non-empty array`);
+  }
+  const properties = definition.schema?.properties;
+  if (!properties || typeof properties !== "object" || Array.isArray(properties) || Object.keys(properties).length === 0) {
+    throw new Error(`flow.json for "${flowName}": "schema.properties" must be a non-empty object`);
+  }
+  if (definition.contractVersion !== void 0) {
+    const version = definition.contractVersion;
+    if (!Number.isInteger(version) || version < 1 || version > CURRENT_FLOW_CONTRACT_VERSION) {
+      throw new Error(
+        `flow.json for "${flowName}": "contractVersion" ${JSON.stringify(version)} is not supported (this loader understands versions 1 through ${CURRENT_FLOW_CONTRACT_VERSION})`
+      );
+    }
+  }
+}
+async function loadFlow(flowsDir, flowName, logger) {
   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 handlerPath = findModulePath(flowPath, "handler");
+  if (!handlerPath) {
+    throw new Error(
+      `no handler found for ${flowName} (looked for ${MODULE_EXTENSIONS.map((ext) => `handler.${ext}`).join(", ")})`
+    );
   }
-  const definition = JSON.parse((0, import_node_fs.readFileSync)(definitionPath, "utf-8"));
+  const rawDefinition = JSON.parse((0, import_node_fs.readFileSync)(definitionPath, "utf-8"));
+  validateFlowDefinition(rawDefinition, flowName);
+  const definition = {
+    ...rawDefinition,
+    contractVersion: rawDefinition.contractVersion ?? CURRENT_FLOW_CONTRACT_VERSION
+  };
   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`);
+    throw new Error(`Flow ${flowName} ${(0, import_node_path.basename)(handlerPath)} must export an 'execute' function`);
   }
-  const prefillPath = (0, import_node_path.join)(flowPath, "prefill.ts");
+  const prefillPath = findModulePath(flowPath, "prefill");
   let prefill;
-  if ((0, import_node_fs.existsSync)(prefillPath)) {
+  if (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`
+      logger.warn(
+        `[flows] "${flowName}" ${(0, import_node_path.basename)(prefillPath)} does not export a prefillFromContext function`
       );
     }
   }
   return { definition, handler, instructionsPath, prefill };
 }
+function findModulePath(flowPath, base) {
+  for (const ext of MODULE_EXTENSIONS) {
+    const candidate = (0, import_node_path.join)(flowPath, `${base}.${ext}`);
+    if ((0, import_node_fs.existsSync)(candidate)) {
+      return candidate;
+    }
+  }
+  return void 0;
+}
 
 // src/flows/params.ts
 var import_node_fs2 = require("node:fs");
@@ -288,7 +345,8 @@ function createFlowEngine(options) {
     cancelMessage = DEFAULT_CANCEL_MESSAGE,
     errorMessage = DEFAULT_ERROR_MESSAGE,
     sessionTtlMs,
-    now = Date.now
+    now = Date.now,
+    logger = createConsoleLogger()
   } = options;
   let registry = createFlowRegistry(/* @__PURE__ */ new Map());
   async function matchFlow(message, conversationContext) {
@@ -297,7 +355,14 @@ function createFlowEngine(options) {
     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);
+    const detection = await detectIntent(
+      client,
+      model,
+      message,
+      flowMap,
+      conversationContext,
+      logger
+    );
     if (detection.confidence >= minConfidence) {
       return registry.getFlow(detection.intent);
     }
@@ -331,7 +396,7 @@ function createFlowEngine(options) {
   }
   return {
     async loadFlows() {
-      const flows = await loadFlowsFromDirectory(flowsDir);
+      const flows = await loadFlowsFromDirectory(flowsDir, logger);
       registry = createFlowRegistry(flows, criticalKeywords);
     },
     getFlow(id) {
@@ -471,6 +536,7 @@ function createTursoFlowSessionStore(client, tableName = "flow_sessions") {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CURRENT_FLOW_CONTRACT_VERSION,
   createFlowEngine,
   createFlowRegistry,
   createTursoFlowSessionStore,