@falai/agent 1.2.8 → 2.0.1

package/dist/utils/session.js

@@ -1,4 +1,5 @@
 import { cloneDeep } from "./clone";
+import { logger } from "./logger";
 export function createSession(sessionIdOrState, metadata) {
     // Overload 2: partial state object
     if (typeof sessionIdOrState === "object" && sessionIdOrState !== null) {
@@ -9,10 +10,11 @@ export function createSession(sessionIdOrState, metadata) {
         return {
             id,
             data: state.data ?? {},
-            routeHistory: state.routeHistory ?? [],
-            currentRoute: state.currentRoute,
+            flowHistory: state.flowHistory ?? [],
+            currentFlow: state.currentFlow,
             currentStep: state.currentStep,
-            pendingTransition: state.pendingTransition,
+            pendingDirective: state.pendingDirective,
+            signals: state.signals,
             history: state.history,
             metadata: {
                 createdAt: now,
@@ -27,7 +29,7 @@ export function createSession(sessionIdOrState, metadata) {
     return {
         id,
         data: {},
-        routeHistory: [],
+        flowHistory: [],
         metadata: {
             ...metadata,
             createdAt: new Date(),
@@ -48,33 +50,33 @@ export function cloneSession(session) {
     return cloneDeep(session);
 }
 /**
- * Helper to update session with new route
- * With agent-level data, routes share the same data structure
+ * Helper to update session with new flow
+ * With agent-level data, flows share the same data structure
  */
-export function enterRoute(session, routeId, routeTitle) {
-    // Exit current route if exists
-    const routeHistory = [...(session.routeHistory || [])];
-    if (session.currentRoute) {
-        const lastRouteIndex = routeHistory.findIndex((r) => r.routeId === session.currentRoute?.id && !r.exitedAt);
-        if (lastRouteIndex >= 0) {
-            routeHistory[lastRouteIndex].exitedAt = new Date();
+export function enterFlow(session, flowId, flowTitle) {
+    // Exit current flow if exists
+    const flowHistory = [...(session.flowHistory || [])];
+    if (session.currentFlow) {
+        const lastFlowIndex = flowHistory.findIndex((r) => r.flowId === session.currentFlow?.id && !r.exitedAt);
+        if (lastFlowIndex >= 0) {
+            flowHistory[lastFlowIndex].exitedAt = new Date();
         }
     }
-    // Enter new route - data persists across routes at agent level
+    // Enter new flow - data persists across flows at agent level
     const now = new Date();
     return {
         ...session,
-        currentRoute: {
-            id: routeId,
-            title: routeTitle,
+        currentFlow: {
+            id: flowId,
+            title: flowTitle,
             enteredAt: now,
         },
         currentStep: undefined,
-        // data remains the same - shared across all routes
-        routeHistory: [
-            ...routeHistory,
+        // data remains the same - shared across all flows
+        flowHistory: [
+            ...flowHistory,
             {
-                routeId,
+                flowId: flowId,
                 enteredAt: now,
                 completed: false,
             },
@@ -102,6 +104,71 @@ export function enterStep(session, stepId, stepDescription) {
         },
     };
 }
+/**
+ * Helper to release the session to idle state on flow completion.
+ *
+ * Marks the active flow's `flowHistory` entry as completed (sets
+ * `completed: true` and `exitedAt: <now>`), clears `currentFlow` and
+ * `currentStep`, and (when `clearOwnedFields` is provided) removes those
+ * fields from `session.data` to support `flow.reentrant` re-entry.
+ *
+ * Does **not** generate any message, copy, or LLM call. The framework
+ * speaks no text of its own at the completion boundary — the developer
+ * controls every word emitted to the user via flow steps.
+ */
+export function completeCurrentFlow(session, options) {
+    const now = new Date();
+    const flowHistory = [...(session.flowHistory || [])];
+    if (session.currentFlow) {
+        const lastFlowIndex = flowHistory.findIndex((entry) => entry.flowId === session.currentFlow?.id && !entry.exitedAt);
+        if (lastFlowIndex >= 0) {
+            flowHistory[lastFlowIndex] = {
+                ...flowHistory[lastFlowIndex],
+                exitedAt: now,
+                completed: true,
+            };
+        }
+    }
+    let nextData = session.data;
+    if (options?.clearOwnedFields && options.clearOwnedFields.length > 0) {
+        const owned = new Set(options.clearOwnedFields);
+        const filtered = {};
+        for (const key of Object.keys(session.data ?? {})) {
+            if (!owned.has(key)) {
+                filtered[key] =
+                    session.data[key];
+            }
+        }
+        nextData = filtered;
+    }
+    return {
+        ...session,
+        currentFlow: undefined,
+        currentStep: undefined,
+        flowHistory,
+        data: nextData,
+        metadata: {
+            ...session.metadata,
+            lastUpdatedAt: now,
+        },
+    };
+}
+/**
+ * Returns true when the given flow id has a most-recent `flowHistory`
+ * entry marked as completed within this session. Used by the router to
+ * exclude completed flows from candidate scoring (unless the flow is
+ * `reentrant`).
+ */
+export function isFlowCompletedThisSession(session, flowId) {
+    const history = session.flowHistory ?? [];
+    for (let i = history.length - 1; i >= 0; i--) {
+        const entry = history[i];
+        if (entry.flowId === flowId) {
+            return entry.completed === true;
+        }
+    }
+    return false;
+}
 /**
  * Helper to merge collected data into session
  * Updates agent-level data structure
@@ -125,17 +192,31 @@ export function mergeCollected(session, data) {
  * Used when saving to database
  */
 export function sessionStepToData(session) {
+    // Strip PreDirective fields before persisting pendingDirective
+    let pendingDirective;
+    if (session.pendingDirective) {
+        pendingDirective = stripPreDirectiveFields(session.pendingDirective);
+    }
+    const collectedData = {
+        data: session.data || {},
+        flowHistory: session.flowHistory,
+        history: session.history,
+        currentFlowTitle: session.currentFlow?.title,
+        currentStepDescription: session.currentStep?.description,
+        metadata: session.metadata,
+    };
+    // Only include pendingDirective when defined (omit key when undefined)
+    if (pendingDirective !== undefined) {
+        collectedData.pendingDirective = pendingDirective;
+    }
+    // Pass through signals bit-identical (reserved for v2.x)
+    if (session.signals !== undefined) {
+        collectedData.signals = session.signals;
+    }
     return {
-        currentRoute: session.currentRoute?.id,
+        currentFlow: session.currentFlow?.id,
         currentStep: session.currentStep?.id,
-        collectedData: {
-            data: session.data || {},
-            routeHistory: session.routeHistory,
-            history: session.history, // Include conversation history
-            currentRouteTitle: session.currentRoute?.title,
-            currentStepDescription: session.currentStep?.description,
-            metadata: session.metadata,
-        },
+        collectedData,
     };
 }
 /**
@@ -147,18 +228,18 @@ export function sessionStepToData(session) {
 export function sessionDataToStep(sessionId, data) {
     const collectedData = data.collectedData || {
         data: {},
-        routeHistory: [],
+        flowHistory: [],
         history: [],
         metadata: {},
-        currentRouteTitle: undefined,
+        currentFlowTitle: undefined,
         currentStepDescription: undefined,
     };
-    return {
+    const session = {
         id: sessionId,
-        currentRoute: data.currentRoute
+        currentFlow: data.currentFlow
             ? {
-                id: data.currentRoute,
-                title: collectedData.currentRouteTitle || data.currentRoute,
+                id: data.currentFlow,
+                title: collectedData.currentFlowTitle || data.currentFlow,
                 enteredAt: new Date(),
             }
             : undefined,
@@ -170,9 +251,84 @@ export function sessionDataToStep(sessionId, data) {
             }
             : undefined,
         data: collectedData.data || {},
-        routeHistory: collectedData.routeHistory || [],
+        flowHistory: collectedData.flowHistory || [],
         history: collectedData.history || [],
         metadata: collectedData.metadata || {},
     };
+    // Restore pendingDirective if present (ignore any legacy pendingTransition — per Req 12.3)
+    if (collectedData.pendingDirective !== undefined) {
+        session.pendingDirective = collectedData.pendingDirective;
+    }
+    // Restore signals bit-identical (reserved for v2.x)
+    if (collectedData.signals !== undefined) {
+        session.signals = collectedData.signals;
+    }
+    return session;
+}
+/**
+ * Strip PreDirective-only fields from a directive before persistence.
+ *
+ * `appendPrompt`, `injectTools`, and `halt` are transient (one-turn lifetime)
+ * and must not be serialized. This is a belt-and-suspenders safety net —
+ * `Agent.dispatch` already strips before setting `pendingDirective`, and the
+ * DirectiveBus's post-LLM drain strips from post-LLM emitters. This function
+ * ensures the persistence layer never writes these fields regardless of the
+ * upstream path.
+ */
+function stripPreDirectiveFields(directive) {
+    const raw = directive;
+    if (!raw.appendPrompt && !raw.injectTools && raw.halt === undefined) {
+        return directive;
+    }
+    const { appendPrompt, injectTools, halt, ...rest } = raw;
+    const droppedFields = [
+        appendPrompt && "appendPrompt",
+        injectTools && "injectTools",
+        halt !== undefined && "halt",
+    ].filter(Boolean);
+    if (droppedFields.length > 0) {
+        logger.debug(`[createPersistedState] Stripped PreDirective-only fields before persistence: ${droppedFields.join(", ")}`);
+    }
+    return rest;
+}
+/**
+ * Prepare a session state for persistence by stripping transient fields.
+ *
+ * This is the shared helper that every persistence adapter should call before
+ * writing session state. It ensures:
+ * - `pendingDirective` has PreDirective-only fields (`appendPrompt`,
+ *   `injectTools`, `halt`) stripped (these are one-turn-lifetime and not
+ *   serializable across turns).
+ * - `pendingDirective` is omitted from the result when `undefined` (adapters
+ *   should not store a null/undefined key).
+ * - `signals` is passed through bit-identical (reserved for v2.x Signals).
+ * - Never writes `pendingTransition`.
+ *
+ * @param session - The in-memory session state to prepare for persistence.
+ * @returns A new session state object safe for serialization.
+ */
+export function createPersistedState(session) {
+    let pendingDirective = session.pendingDirective;
+    if (pendingDirective) {
+        pendingDirective = stripPreDirectiveFields(pendingDirective);
+    }
+    // Build the persisted state — omit pendingDirective key entirely when undefined
+    const persisted = {
+        id: session.id,
+        data: session.data,
+        flowHistory: session.flowHistory,
+        currentFlow: session.currentFlow,
+        currentStep: session.currentStep,
+        history: session.history,
+        metadata: session.metadata,
+    };
+    if (pendingDirective !== undefined) {
+        persisted.pendingDirective = pendingDirective;
+    }
+    // Pass through signals bit-identical (reserved for v2.x)
+    if (session.signals !== undefined) {
+        persisted.signals = session.signals;
+    }
+    return persisted;
 }
 //# sourceMappingURL=session.js.map

package/dist/utils/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/utils/session.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/utils/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAIpC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAmBlC,MAAM,UAAU,aAAa,CAC3B,gBAAwD,EACxD,QAA0C;IAE1C,mCAAmC;IACnC,IAAI,OAAO,gBAAgB,KAAK,QAAQ,IAAI,gBAAgB,KAAK,IAAI,EAAE,CAAC;QACtE,MAAM,KAAK,GAAG,gBAAgB,CAAC;QAC/B,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,EAAE,GACN,KAAK,CAAC,EAAE;YACR,WAAW,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAEjE,OAAO;YACL,EAAE;YACF,IAAI,EAAE,KAAK,CAAC,IAAI,IAAK,EAAqB;YAC1C,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,EAAE;YACpC,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;YACxC,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,QAAQ,EAAE;gBACR,SAAS,EAAE,GAAG;gBACd,aAAa,EAAE,GAAG;gBAClB,GAAG,KAAK,CAAC,QAAQ;aAClB;SACF,CAAC;IACJ,CAAC;IAED,mCAAmC;IACnC,MAAM,EAAE,GACN,gBAAgB;QAChB,WAAW,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAEjE,OAAO;QACL,EAAE;QACF,IAAI,EAAE,EAAoB;QAC1B,WAAW,EAAE,EAAE;QACf,QAAQ,EAAE;YACR,GAAG,QAAQ;YACX,SAAS,EAAE,IAAI,IAAI,EAAE;YACrB,aAAa,EAAE,IAAI,IAAI,EAAE;SAC1B;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,WAAW,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AACxE,CAAC;AACD;;GAEG;AACH,MAAM,UAAU,YAAY,CAC1B,OAA4B;IAE5B,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CACvB,OAA4B,EAC5B,MAAc,EACd,SAAiB;IAEjB,8BAA8B;IAC9B,MAAM,WAAW,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,CAAC;IACrD,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,MAAM,aAAa,GAAG,WAAW,CAAC,SAAS,CACzC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,OAAO,CAAC,WAAW,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,QAAQ,CAC3D,CAAC;QACF,IAAI,aAAa,IAAI,CAAC,EAAE,CAAC;YACvB,WAAW,CAAC,aAAa,CAAC,CAAC,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC;QACnD,CAAC;IACH,CAAC;IAED,6DAA6D;IAC7D,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,OAAO;QACL,GAAG,OAAO;QACV,WAAW,EAAE;YACX,EAAE,EAAE,MAAM;YACV,KAAK,EAAE,SAAS;YAChB,SAAS,EAAE,GAAG;SACf;QACD,WAAW,EAAE,SAAS;QACtB,kDAAkD;QAClD,WAAW,EAAE;YACX,GAAG,WAAW;YACd;gBACE,MAAM,EAAE,MAAM;gBACd,SAAS,EAAE,GAAG;gBACd,SAAS,EAAE,KAAK;aACjB;SACF;QACD,QAAQ,EAAE;YACR,GAAG,OAAO,CAAC,QAAQ;YACnB,aAAa,EAAE,GAAG;SACnB;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CACvB,OAA4B,EAC5B,MAAc,EACd,eAAwB;IAExB,OAAO;QACL,GAAG,OAAO;QACV,WAAW,EAAE;YACX,EAAE,EAAE,MAAM;YACV,WAAW,EAAE,eAAe;YAC5B,SAAS,EAAE,IAAI,IAAI,EAAE;SACtB;QACD,QAAQ,EAAE;YACR,GAAG,OAAO,CAAC,QAAQ;YACnB,aAAa,EAAE,IAAI,IAAI,EAAE;SAC1B;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAA4B,EAC5B,OAA2D;IAE3D,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,WAAW,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,CAAC;IAErD,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,MAAM,aAAa,GAAG,WAAW,CAAC,SAAS,CACzC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,OAAO,CAAC,WAAW,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CACvE,CAAC;QACF,IAAI,aAAa,IAAI,CAAC,EAAE,CAAC;YACvB,WAAW,CAAC,aAAa,CAAC,GAAG;gBAC3B,GAAG,WAAW,CAAC,aAAa,CAAC;gBAC7B,QAAQ,EAAE,GAAG;gBACb,SAAS,EAAE,IAAI;aAChB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAC5B,IAAI,OAAO,EAAE,gBAAgB,IAAI,OAAO,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrE,MAAM,KAAK,GAAG,IAAI,GAAG,CAAc,OAAO,CAAC,gBAAgB,CAAC,CAAC;QAC7D,MAAM,QAAQ,GAAmB,EAAE,CAAC;QACpC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAoB,EAAE,CAAC;YACrE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACnB,QAAyC,CAAC,GAAG,CAAC;oBAC5C,OAAO,CAAC,IAAqC,CAAC,GAAG,CAAC,CAAC;YACxD,CAAC;QACH,CAAC;QACD,QAAQ,GAAG,QAAQ,CAAC;IACtB,CAAC;IAED,OAAO;QACL,GAAG,OAAO;QACV,WAAW,EAAE,SAAS;QACtB,WAAW,EAAE,SAAS;QACtB,WAAW;QACX,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE;YACR,GAAG,OAAO,CAAC,QAAQ;YACnB,aAAa,EAAE,GAAG;SACnB;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAA4B,EAC5B,MAAc;IAEd,MAAM,OAAO,GAAG,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC;IAC1C,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC5B,OAAO,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC;QAClC,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,OAA4B,EAC5B,IAAsB;IAEtB,MAAM,YAAY,GAAG;QACnB,GAAG,OAAO,CAAC,IAAI;QACf,GAAG,IAAI;KACU,CAAC;IAEpB,OAAO;QACL,GAAG,OAAO;QACV,IAAI,EAAE,YAAY,EAAE,0BAA0B;QAC9C,QAAQ,EAAE;YACR,GAAG,OAAO,CAAC,QAAQ;YACnB,aAAa,EAAE,IAAI,IAAI,EAAE;SAC1B;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA4B;IAM5B,+DAA+D;IAC/D,IAAI,gBAAqE,CAAC;IAC1E,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;QAC7B,gBAAgB,GAAG,uBAAuB,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,aAAa,GAA8B;QAC/C,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,EAAE;QACxB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,gBAAgB,EAAE,OAAO,CAAC,WAAW,EAAE,KAAK;QAC5C,sBAAsB,EAAE,OAAO,CAAC,WAAW,EAAE,WAAW;QACxD,QAAQ,EAAE,OAAO,CAAC,QAAQ;KAC3B,CAAC;IAEF,uEAAuE;IACvE,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACnC,aAAa,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;IACpD,CAAC;IAED,yDAAyD;IACzD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,aAAa,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAC1C,CAAC;IAED,OAAO;QACL,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,EAAE;QACpC,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,EAAE;QACpC,aAAa;KACd,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAiB,EACjB,IAIC;IAED,MAAM,aAAa,GAA8B,IAAI,CAAC,aAAa,IAAI;QACrE,IAAI,EAAE,EAAE;QACR,WAAW,EAAE,EAAE;QACf,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE,EAAE;QACZ,gBAAgB,EAAE,SAAS;QAC3B,sBAAsB,EAAE,SAAS;KAClC,CAAC;IAEF,MAAM,OAAO,GAAwB;QACnC,EAAE,EAAE,SAAS;QACb,WAAW,EAAE,IAAI,CAAC,WAAW;YAC3B,CAAC,CAAC;gBACA,EAAE,EAAE,IAAI,CAAC,WAAW;gBACpB,KAAK,EAAE,aAAa,CAAC,gBAAgB,IAAI,IAAI,CAAC,WAAW;gBACzD,SAAS,EAAE,IAAI,IAAI,EAAE;aACtB;YACD,CAAC,CAAC,SAAS;QACb,WAAW,EAAE,IAAI,CAAC,WAAW;YAC3B,CAAC,CAAC;gBACA,EAAE,EAAE,IAAI,CAAC,WAAW;gBACpB,WAAW,EAAE,aAAa,CAAC,sBAAsB,IAAI,SAAS;gBAC9D,SAAS,EAAE,IAAI,IAAI,EAAE;aACtB;YACD,CAAC,CAAC,SAAS;QACb,IAAI,EAAE,aAAa,CAAC,IAAI,IAAI,EAAE;QAC9B,WAAW,EAAE,aAAa,CAAC,WAAW,IAAI,EAAE;QAC5C,OAAO,EAAE,aAAa,CAAC,OAAO,IAAI,EAAE;QACpC,QAAQ,EAAE,aAAa,CAAC,QAAQ,IAAI,EAAE;KACvC,CAAC;IAEF,2FAA2F;IAC3F,IAAI,aAAa,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACjD,OAAO,CAAC,gBAAgB,GAAG,aAAa,CAAC,gBAAgB,CAAC;IAC5D,CAAC;IAED,oDAAoD;IACpD,IAAI,aAAa,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACxC,OAAO,CAAC,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC;IAC1C,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAGD;;;;;;;;;GASG;AACH,SAAS,uBAAuB,CAC9B,SAAoC;IAEpC,MAAM,GAAG,GAAG,SAAoC,CAAC;IACjD,IAAI,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACpE,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,GAAG,GAAG,CAAC;IAEzD,MAAM,aAAa,GAAG;QACpB,YAAY,IAAI,cAAc;QAC9B,WAAW,IAAI,aAAa;QAC5B,IAAI,KAAK,SAAS,IAAI,MAAM;KAC7B,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAElB,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,CAAC,KAAK,CACV,gFAAgF,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3G,CAAC;IACJ,CAAC;IAED,OAAO,IAAiC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAA4B;IAE5B,IAAI,gBAAgB,GAClB,OAAO,CAAC,gBAAgB,CAAC;IAE3B,IAAI,gBAAgB,EAAE,CAAC;QACrB,gBAAgB,GAAG,uBAAuB,CAAC,gBAAgB,CAAC,CAAC;IAC/D,CAAC;IAED,gFAAgF;IAChF,MAAM,SAAS,GAAwB;QACrC,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,QAAQ,EAAE,OAAO,CAAC,QAAQ;KAC3B,CAAC;IAEF,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACnC,SAAS,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;IAChD,CAAC;IAED,yDAAyD;IACzD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,SAAS,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACtC,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/docs/README.md

@@ -1,218 +1,40 @@
-# @falai/agent Documentation
-
-Welcome to the `@falai/agent` documentation! This comprehensive framework enables you to build sophisticated, type-safe conversational AI agents with **AI-powered routing**, **schema-driven data extraction**, and **declarative conversation flows**.
-
-## ✨ What Makes @falai/agent Unique
-
-- 🤖 **AI-Powered Routing**: Intelligent route and step selection based on conversation context and user intent
-- 🎯 **Schema-First Data Collection**: Type-safe, structured data extraction from natural conversations
-- 🔀 **Route DSL**: Fluent, composable API for building complex multi-step conversation flows
-- 🏗️ **Type-Safe Context**: Generic context management with lifecycle hooks and dynamic providers
-- 🔄 **Streaming & Tools**: Real-time streaming responses with dynamic tool execution using unified Tool interface
-- 💾 **Comprehensive Persistence**: Database-agnostic session and message storage across multiple adapters
-- 🛠️ **Unified Tool System**: Simplified tool creation with flexible return types and powerful pattern helpers
-
-## 📖 Documentation Structure
-
-### 🚀 Getting Started
-
-- **[Quick Start Guide](./guides/getting-started/README.md)** - Build your first agent in 15 minutes
-
-### 🏗️ Core Framework
-
-#### Agent Architecture
-
-- **[Agent Overview](./core/agent/README.md)** - Agent lifecycle, configuration & hooks
-- **[Context Management](./core/agent/context-management.md)** - Dynamic context providers & updates
-- **[Session Management](./core/agent/session-management.md)** - Session persistence & state
-- **[Rules & Prohibitions](./core/agent/rules-and-prohibitions.md)** - Agent-wide behavioral boundaries
-
-#### AI Routing System
-
-- **[Intelligent Routing](./core/routing/intelligent-routing.md)** - AI-powered route and step selection
-- **[Route DSL](./core/conversation-flows/route-dsl.md)** - Declarative conversation flow design
-- **[Step Transitions](./core/conversation-flows/step-transitions.md)** - Conditional logic and branching
-
-#### Conversation Flows
-
-- **[Routes](./core/conversation-flows/routes.md)** - Route definition, lifecycle & completion
-- **[Steps](./core/conversation-flows/steps.md)** - Step configuration, data collection & validation
-- **[Data Collection](./core/conversation-flows/data-collection.md)** - Agent-level schema-driven data extraction
-
-#### AI Integration
-
-- **[AI Providers](./core/ai-integration/providers.md)** - Gemini, OpenAI, Anthropic, OpenRouter
-- **[Prompt Composition](./core/ai-integration/prompt-composition.md)** - How prompts are built with context
-- **[Response Processing](./core/ai-integration/response-processing.md)** - Schema extraction & tool calls
-
-#### Tools & Execution
-
-- **[Tool Definition](./core/tools/tool-definition.md)** - Creating and configuring tools
-- **[Tool Scoping](./core/tools/tool-scoping.md)** - Agent, route, and step-level tool management
-
-#### Persistence
-
-- **[Session Storage](./core/persistence/session-storage.md)** - Session persistence patterns
-- **[Database Adapters](./core/persistence/adapters.md)** - Built-in adapter configurations
-
-#### Error Handling
-
-- **[Error Handling](./core/error-handling.md)** - Comprehensive error handling patterns and recovery strategies
-- **[Error Handling Patterns](./guides/error-handling-patterns.md)** - Practical patterns for streaming, routing, and data sync errors
-
-### 🚀 Advanced Guides
-
-- **[Advanced Patterns](./guides/advanced-patterns/)** - Complex use cases & integrations
-- **[Migration Guides](./guides/migration/)** - Upgrade guides for major changes
-- **[API Reference](./api/README.md)** - Complete API documentation
-
-## 🎯 Quick Links
-
-### By Learning Path
-
-**🚀 First time here?**
-→ Start with [Quick Start Guide](./guides/getting-started/README.md)
-
-**🏗️ Understanding the design?**
-→ Read [Agent Overview](./core/agent/README.md) then [Intelligent Routing](./core/routing/intelligent-routing.md)
-
-**🤖 Building AI-powered conversations?**
-→ See [Route DSL](./core/conversation-flows/route-dsl.md), [Intelligent Routing](./core/routing/intelligent-routing.md), and [Step Transitions](./core/conversation-flows/step-transitions.md)
-
-**🎯 Collecting structured data?**
-→ Learn [Agent-Level Data Collection](./core/conversation-flows/data-collection.md) and [Schema-Driven Extraction](../examples/core-concepts/schema-driven-extraction.ts)
-
-**🔧 Working with tools?**
-→ See [Tool Definition](./core/tools/tool-definition.md) and [Tool Scoping](./core/tools/tool-scoping.md)
-
-**💾 Need persistence?**
-→ See [Session Storage](./core/persistence/session-storage.md) and [Database Adapters](./core/persistence/adapters.md)
-
-**🚀 Going to production?**
-→ Check [Advanced Patterns](./guides/advanced-patterns/) and [Server Session Management](../examples/integrations/server-session-management.ts)
-
-### By Topic
-
-- **Agent Architecture**: [Agent](./core/agent/README.md) | [Context](./core/agent/context-management.md) | [Sessions](./core/agent/session-management.md)
-- **AI Routing System**: [Intelligent Routing](./core/routing/intelligent-routing.md) | [Route DSL](./core/conversation-flows/route-dsl.md) | [Step Transitions](./core/conversation-flows/step-transitions.md)
-- **Conversation Flows**: [Routes](./core/conversation-flows/routes.md) | [Steps](./core/conversation-flows/steps.md) | [Agent-Level Data Collection](./core/conversation-flows/data-collection.md)
-- **AI Integration**: [Providers](./core/ai-integration/providers.md) | [Prompts](./core/ai-integration/prompt-composition.md) | [Responses](./core/ai-integration/response-processing.md)
-- **Tools & Execution**: [Tool Definition](./core/tools/tool-definition.md) | [Tool Scoping](./core/tools/tool-scoping.md)
-- **Persistence**: [Session Storage](./core/persistence/session-storage.md) | [Adapters](./core/persistence/adapters.md)
-- **Error Handling**: [Core Error Handling](./core/error-handling.md) | [Error Patterns](./guides/error-handling-patterns.md)
-- **Advanced**: [Patterns](./guides/advanced-patterns/) | [Migration](./guides/migration/) | [API Reference](./api/)
-
-## 💡 Examples by Domain
-
-Check out the [`examples/`](../examples/) directory for complete, runnable examples organized by architectural domain:
-
-### 🏗️ Core Concepts
-
-- **[Basic Agent](../examples/core-concepts/basic-agent.ts)** - Minimal agent setup and configuration
-- **[Schema-Driven Extraction](../examples/core-concepts/schema-driven-extraction.ts)** - Type-safe data collection with JSON Schema
-- **[Session Management](../examples/core-concepts/session-management.ts)** - Multi-turn conversations with persistence
-- **[Modern Streaming API](../examples/core-concepts/modern-streaming-api.ts)** - Streaming responses with the modern API
-
-### 🤖 AI Routing System
-
-- **[Completion Transitions](../examples/conversation-flows/completion-transitions.ts)** - Automatic route transitions when flows complete
-
-### 💬 Conversation Flows
-
-- **[Knowledge-Based Agent](../examples/advanced-patterns/knowledge-based-agent.ts)** - Agents with domain-specific knowledge bases
-- **[Persistent Onboarding](../examples/advanced-patterns/persistent-onboarding.ts)** - Multi-step onboarding with data persistence
-
-### 🤖 AI Providers
-
-- **[OpenAI Integration](../examples/ai-providers/openai-integration.ts)** - GPT-4 and GPT-3.5 Turbo with backup models
-- **[Anthropic Integration](../examples/ai-providers/anthropic-integration.ts)** - Claude with streaming and tool calling
-
-### 🔧 Tools & Execution
-
-- **[Basic Tools](../examples/tools/basic-tools.ts)** - Unified Tool interface with simple return values
-- **[Data Enrichment Tools](../examples/tools/data-enrichment-tools.ts)** - Pattern helpers for data modification
-
-### 💾 Persistence
-
-- **[Memory Sessions](../examples/persistence/memory-sessions.ts)** - In-memory session management
-- **[Redis Persistence](../examples/persistence/redis-persistence.ts)** - High-performance Redis storage
-- **[Database Persistence](../examples/persistence/database-persistence.ts)** - SQL/NoSQL database integration
-- **[Custom Adapter](../examples/persistence/custom-adapter.ts)** - Build custom persistence adapters
-
-### 🚀 Advanced Patterns
-
-- **[Streaming Responses](../examples/advanced-patterns/streaming-responses.ts)** - Real-time response streaming
-- **[Route Lifecycle Hooks](../examples/advanced-patterns/route-lifecycle-hooks.ts)** - Custom route behavior and data transformation
-
-### 🔗 Integrations
+---
+title: "Documentation"
+description: "Typed conversations where code stays in charge. Docs for @falai/agent."
+type: overview
+order: 0
+---
 
-- **[Database Integration](../examples/integrations/database-integration.ts)** - Direct database access patterns
-- **[Healthcare Integration](../examples/integrations/healthcare-integration.ts)** - Domain-specific healthcare workflows
-- **[Search Integration](../examples/integrations/search-integration.ts)** - Integration with search engines
-- **[Server Session Management](../examples/integrations/server-session-management.ts)** - Server-side session handling
+# Documentation
 
-## 🤝 Contributing
+**Typed conversations where code stays in charge.**
 
-We welcome contributions to improve the documentation and examples! Here's how you can help:
+Define flows, steps, and tools in TypeScript; the framework calls the LLM only for the parts that need language — routing, extraction, and generation.
 
-### Ways to Contribute
+## New here?
 
-- **📝 Improve Documentation** - Fix typos, clarify explanations, add examples
-- **🎯 Create Examples** - Add examples for new use cases or domains
-- **🔧 Update Code Samples** - Ensure examples work with latest framework versions
-- **📚 Write Guides** - Create tutorials for specific patterns or integrations
-- **🐛 Report Issues** - Found a bug in docs or examples? Let us know!
+Walk through a five-step tutorial that builds a working agent end to end, from install to streaming responses in production.
 
-### Getting Started
+[Start the tutorial](./start/01-install.md)
 
-1. **Fork** the repository
-2. **Clone** your fork: `git clone https://github.com/your-username/agent.git`
-3. **Install** dependencies: `bun install`
-4. **Make changes** in the appropriate domain directory
-5. **Test examples** by running them: `bun run examples/your-example.ts`
-6. **Submit** a pull request
+## Solving one task?
 
-### Documentation Structure
+Eight task-shaped recipes covering conditions, branching, flow control, instructions, persistence, streaming, errors, and compaction.
 
-When adding new content, follow the domain-focused organization:
+[Browse the guides](./guides/conditions.md)
 
-```
-docs/
-├── core/                    # Core framework docs
-│   ├── agent/              # Agent architecture & lifecycle
-│   ├── routing/            # AI routing system & intelligent selection
-│   ├── conversation-flows/ # Route DSL, steps, data collection
-│   ├── ai-integration/     # Providers, prompts, response processing
-│   ├── tools/              # Tool definition, execution, scoping
-│   └── persistence/        # Session storage & database adapters
-└── guides/                 # End-to-end guides
-    └── [guide-name]/       # getting-started, building-agents, etc.
+## Want the why?
 
-examples/
-├── core-concepts/          # Basic agent setup & fundamental concepts
-├── ai-providers/           # AI provider integrations
-├── conversation-flows/     # AI routing & conversation patterns
-├── persistence/            # Session storage implementations
-├── tools/                  # Tool creation & execution patterns
-├── advanced-patterns/      # Complex use cases & integrations
-└── integrations/           # External service integrations
-```
+Three concept pages that build the mental model: the seven primitives, the per-turn pipeline, and how directives steer a conversation.
 
-### Example Contribution Workflow
+[Read about the architecture](./concepts/architecture.md)
 
-1. **Identify the domain** your example belongs to (e.g., `tools`, `persistence`)
-2. **Create the example** in the appropriate domain directory
-3. **Add comprehensive comments** explaining the concepts
-4. **Include error handling** and best practices
-5. **Update documentation** links if needed
-6. **Test thoroughly** before submitting
+## Looking up an API?
 
-### Need Help?
+One page per public type. Signatures, field tables, errors, and short runnable examples for `createAgent`, `Flow`, `Step`, `Tool`, `Instruction`, `Directive`, signals, providers, adapters, and more.
 
-- 📖 **[Contributing Guide](./CONTRIBUTING.md)** - Detailed contribution guidelines
-- 💬 **[Discussions](https://github.com/falai-dev/agent/discussions)** - Ask questions and get help
-- 🐛 **[Issues](https://github.com/falai-dev/agent/issues)** - Report bugs or request features
+[Open the reference](./reference/create-agent.md)
 
 ---
 
-**Made with ❤️ for the community**
+Upgrading from `1.x`? See the [v1 → v2 migration guide](./migration/v1-to-v2.md).