nduka 1.0.0

package/dist/chat-state/execution-gate.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Chat Execution Gate — The Brain
+ *
+ * Single decision point for every inbound message.
+ * ALL routing decisions flow through here BEFORE any AI or storage logic.
+ *
+ * Based on research:
+ *  - Baileys fromMe is unreliable (Issue #2000) → owner_jid match is PRIMARY
+ *  - Messages are not ordered reliably → state-driven, not time-driven
+ *  - Reconnection replays events → last_event_id dedup
+ *
+ * Decision matrix:
+ *   AI_ACTIVE + customer msg → ALLOW_AI
+ *   AI_ACTIVE + owner msg    → OWNER_OVERRIDE
+ *   HUMAN_ACTIVE + customer  → BLOCK (store only)
+ *   HUMAN_ACTIVE + owner     → ALLOW (owner always wins)
+ *   SHARED + anyone           → ALLOW_AI
+ *   ESCALATED + anyone        → BLOCK (owner only)
+ */
+import { ChatMode, ChatStateStore } from './store.js';
+import type { ChatState } from './store.js';
+export type GateDecision = 'ALLOW_AI' | 'ALLOW_OWNER' | 'BLOCK' | 'OWNER_OVERRIDE' | 'DUPLICATE_EVENT';
+export interface GateResult {
+    decision: GateDecision;
+    reason: string;
+    chatState: ChatState;
+    shouldCancelActiveGeneration: boolean;
+}
+export declare class ExecutionGate {
+    private stateStore;
+    constructor(stateStore: ChatStateStore);
+    /**
+     * THE SINGLE DECISION POINT.
+     * Every inbound message passes through here.
+     *
+     * @param chatId The chat JID
+     * @param eventId The message/event ID (for dedup)
+     * @param isOwnerMessage Whether the sender is the owner (by JID match, NOT fromMe)
+     * @param isGroup Whether this is a group chat
+     * @param fromMe Raw Baileys fromMe field (hint only, not authoritative)
+     */
+    evaluate(params: {
+        chatId: string;
+        eventId: string;
+        isOwnerMessage: boolean;
+        isGroup: boolean;
+        fromMe?: boolean;
+    }): GateResult;
+    /**
+     * Check if a message should trigger auto-takeover.
+     * When owner replies in an AI_ACTIVE chat, transition to HUMAN_ACTIVE.
+     */
+    shouldAutoTakeover(chatId: string, isOwnerMessage: boolean, fromMe: boolean): boolean;
+    /**
+     * Transition chat mode with version check.
+     */
+    transitionMode(chatId: string, newMode: ChatMode): {
+        success: boolean;
+        state: ChatState;
+    };
+    /**
+     * Get the state store (for querying).
+     */
+    getStateStore(): ChatStateStore;
+}
+//# sourceMappingURL=execution-gate.d.ts.map

package/dist/chat-state/execution-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-gate.d.ts","sourceRoot":"","sources":["../../src/chat-state/execution-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5C,MAAM,MAAM,YAAY,GACpB,UAAU,GACV,aAAa,GACb,OAAO,GACP,gBAAgB,GAChB,iBAAiB,CAAC;AAEtB,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;IACrB,4BAA4B,EAAE,OAAO,CAAC;CACvC;AAID,qBAAa,aAAa;IACxB,OAAO,CAAC,UAAU,CAAiB;gBAEvB,UAAU,EAAE,cAAc;IAItC;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,EAAE;QACf,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,cAAc,EAAE,OAAO,CAAC;QACxB,OAAO,EAAE,OAAO,CAAC;QACjB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,GAAG,UAAU;IA2Fd;;;OAGG;IACH,kBAAkB,CAChB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,OAAO,EACvB,MAAM,EAAE,OAAO,GACd,OAAO;IAWV;;OAEG;IACH,cAAc,CACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,QAAQ,GAChB;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,SAAS,CAAA;KAAE;IAIzC;;OAEG;IACH,aAAa,IAAI,cAAc;CAGhC"}

package/dist/chat-state/execution-gate.js

@@ -0,0 +1,143 @@
+/**
+ * Chat Execution Gate — The Brain
+ *
+ * Single decision point for every inbound message.
+ * ALL routing decisions flow through here BEFORE any AI or storage logic.
+ *
+ * Based on research:
+ *  - Baileys fromMe is unreliable (Issue #2000) → owner_jid match is PRIMARY
+ *  - Messages are not ordered reliably → state-driven, not time-driven
+ *  - Reconnection replays events → last_event_id dedup
+ *
+ * Decision matrix:
+ *   AI_ACTIVE + customer msg → ALLOW_AI
+ *   AI_ACTIVE + owner msg    → OWNER_OVERRIDE
+ *   HUMAN_ACTIVE + customer  → BLOCK (store only)
+ *   HUMAN_ACTIVE + owner     → ALLOW (owner always wins)
+ *   SHARED + anyone           → ALLOW_AI
+ *   ESCALATED + anyone        → BLOCK (owner only)
+ */
+import { ChatMode } from './store.js';
+// ─── Execution Gate ──────────────────────────────────────────────────────────
+export class ExecutionGate {
+    stateStore;
+    constructor(stateStore) {
+        this.stateStore = stateStore;
+    }
+    /**
+     * THE SINGLE DECISION POINT.
+     * Every inbound message passes through here.
+     *
+     * @param chatId The chat JID
+     * @param eventId The message/event ID (for dedup)
+     * @param isOwnerMessage Whether the sender is the owner (by JID match, NOT fromMe)
+     * @param isGroup Whether this is a group chat
+     * @param fromMe Raw Baileys fromMe field (hint only, not authoritative)
+     */
+    evaluate(params) {
+        const { chatId, eventId, isOwnerMessage, isGroup, fromMe } = params;
+        // ── Step 1: Event deduplication ──
+        if (eventId && this.stateStore.isEventProcessed(chatId, eventId)) {
+            const state = this.stateStore.get(chatId);
+            return {
+                decision: 'DUPLICATE_EVENT',
+                reason: `Event ${eventId} already processed`,
+                chatState: state,
+                shouldCancelActiveGeneration: false,
+            };
+        }
+        // ── Step 2: Load chat state ──
+        const state = this.stateStore.get(chatId);
+        // ── Step 3: Groups bypass per-chat modes ──
+        if (isGroup) {
+            // Groups are always allowed for AI (unless global toggle is off)
+            this.stateStore.recordEvent(chatId, eventId);
+            return {
+                decision: 'ALLOW_AI',
+                reason: 'Group chat',
+                chatState: state,
+                shouldCancelActiveGeneration: false,
+            };
+        }
+        // ── Step 4: Owner ALWAYS wins ──
+        // NOTE: Use JID match (from OwnerIdentityService) as PRIMARY.
+        // Baileys fromMe is unreliable (Issue #2000) — used only as secondary hint.
+        if (isOwnerMessage) {
+            this.stateStore.recordEvent(chatId, eventId);
+            const shouldCancel = state.mode === ChatMode.AI_ACTIVE;
+            return {
+                decision: state.mode === ChatMode.AI_ACTIVE ? 'OWNER_OVERRIDE' : 'ALLOW_OWNER',
+                reason: 'Owner message detected',
+                chatState: state,
+                shouldCancelActiveGeneration: shouldCancel,
+            };
+        }
+        // ── Step 5: Mode-based decision for customer messages ──
+        // Record event (prevents replay)
+        this.stateStore.recordEvent(chatId, eventId);
+        switch (state.mode) {
+            case ChatMode.AI_ACTIVE:
+                return {
+                    decision: 'ALLOW_AI',
+                    reason: 'AI_ACTIVE mode',
+                    chatState: state,
+                    shouldCancelActiveGeneration: false,
+                };
+            case ChatMode.HUMAN_ACTIVE:
+                return {
+                    decision: 'BLOCK',
+                    reason: 'HUMAN_ACTIVE — owner handling',
+                    chatState: state,
+                    shouldCancelActiveGeneration: false,
+                };
+            case ChatMode.SHARED:
+                return {
+                    decision: 'ALLOW_AI',
+                    reason: 'SHARED mode',
+                    chatState: state,
+                    shouldCancelActiveGeneration: false,
+                };
+            case ChatMode.ESCALATED:
+                return {
+                    decision: 'BLOCK',
+                    reason: 'ESCALATED — owner required',
+                    chatState: state,
+                    shouldCancelActiveGeneration: false,
+                };
+            default:
+                return {
+                    decision: 'ALLOW_AI',
+                    reason: 'Default (AI_ACTIVE)',
+                    chatState: state,
+                    shouldCancelActiveGeneration: false,
+                };
+        }
+    }
+    /**
+     * Check if a message should trigger auto-takeover.
+     * When owner replies in an AI_ACTIVE chat, transition to HUMAN_ACTIVE.
+     */
+    shouldAutoTakeover(chatId, isOwnerMessage, fromMe) {
+        if (!isOwnerMessage)
+            return false;
+        const state = this.stateStore.get(chatId);
+        if (state.mode !== ChatMode.AI_ACTIVE)
+            return false;
+        // Owner replied in AI_ACTIVE chat → takeover
+        // NOTE: fromMe is a HINT, not authoritative. JID match already confirmed ownership.
+        return true;
+    }
+    /**
+     * Transition chat mode with version check.
+     */
+    transitionMode(chatId, newMode) {
+        return this.stateStore.setMode(chatId, newMode);
+    }
+    /**
+     * Get the state store (for querying).
+     */
+    getStateStore() {
+        return this.stateStore;
+    }
+}
+//# sourceMappingURL=execution-gate.js.map

package/dist/chat-state/execution-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-gate.js","sourceRoot":"","sources":["../../src/chat-state/execution-gate.ts"],"names":[],"mappings":"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"}

package/dist/chat-state/index.d.ts

@@ -0,0 +1,7 @@
+export { ChatStateStore, ChatMode } from './store.js';
+export type { ChatState } from './store.js';
+export { ExecutionGate } from './execution-gate.js';
+export type { GateDecision, GateResult } from './execution-gate.js';
+export { validateInvariants, assertInvariants, generateTransitionMatrix } from './invariants.js';
+export type { InvariantViolation } from './invariants.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/chat-state/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/chat-state/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AACjG,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/chat-state/index.js

@@ -0,0 +1,4 @@
+export { ChatStateStore, ChatMode } from './store.js';
+export { ExecutionGate } from './execution-gate.js';
+export { validateInvariants, assertInvariants, generateTransitionMatrix } from './invariants.js';
+//# sourceMappingURL=index.js.map

package/dist/chat-state/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/chat-state/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/chat-state/invariants.d.ts

@@ -0,0 +1,32 @@
+/**
+ * State Invariant Validator
+ *
+ * Enforces: no chat can exist in an impossible state.
+ * Based on "Make Illegal States Unrepresentable" pattern.
+ */
+import { ChatMode, ChatStateStore } from '../chat-state/store.js';
+export interface InvariantViolation {
+    chatId: string;
+    invariant: string;
+    expected: string;
+    actual: string;
+}
+/**
+ * Validate all chats. Returns violations found.
+ */
+export declare function validateInvariants(store: ChatStateStore, activeAIChats: Set<string>): InvariantViolation[];
+/**
+ * Assert that no invariants are violated.
+ * Throws on violation.
+ */
+export declare function assertInvariants(store: ChatStateStore, activeAIChats: Set<string>): void;
+/**
+ * Generate all possible state/event combinations for fuzzing.
+ */
+export declare function generateTransitionMatrix(): Array<{
+    from: ChatMode;
+    event: string;
+    expectedMode: ChatMode;
+    illegal: boolean;
+}>;
+//# sourceMappingURL=invariants.d.ts.map

package/dist/chat-state/invariants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariants.d.ts","sourceRoot":"","sources":["../../src/chat-state/invariants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAIlE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAsBD;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,EACrB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,GACzB,kBAAkB,EAAE,CAuBtB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,cAAc,EACrB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,GACzB,IAAI,CAMN;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,KAAK,CAAC;IAChD,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,QAAQ,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC,CAqCD"}

package/dist/chat-state/invariants.js

@@ -0,0 +1,95 @@
+/**
+ * State Invariant Validator
+ *
+ * Enforces: no chat can exist in an impossible state.
+ * Based on "Make Illegal States Unrepresentable" pattern.
+ */
+import { ChatMode } from '../chat-state/store.js';
+/**
+ * Every chat state pair that MUST NOT coexist.
+ */
+const ILLEGAL_COMBINATIONS = [
+    {
+        mode: ChatMode.ESCALATED,
+        condition: (s) => s.aiActive === true,
+        description: 'ESCALATED + AI active — AI must be disabled when escalated',
+    },
+    {
+        mode: ChatMode.HUMAN_ACTIVE,
+        condition: (s) => s.aiActive === true,
+        description: 'HUMAN_ACTIVE + AI active — AI must be silent during human handling',
+    },
+];
+/**
+ * Validate all chats. Returns violations found.
+ */
+export function validateInvariants(store, activeAIChats) {
+    const violations = [];
+    const states = store.listAll();
+    for (const state of states) {
+        const aiActive = activeAIChats.has(state.chatId);
+        for (const rule of ILLEGAL_COMBINATIONS) {
+            if (state.mode === rule.mode) {
+                const context = { mode: state.mode, aiActive, ownerPresent: true };
+                if (rule.condition(context)) {
+                    violations.push({
+                        chatId: state.chatId,
+                        invariant: rule.description,
+                        expected: `${rule.mode} + AI=INACTIVE`,
+                        actual: `${rule.mode} + AI=${aiActive ? 'ACTIVE' : 'inactive'}`,
+                    });
+                }
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * Assert that no invariants are violated.
+ * Throws on violation.
+ */
+export function assertInvariants(store, activeAIChats) {
+    const violations = validateInvariants(store, activeAIChats);
+    if (violations.length > 0) {
+        const msgs = violations.map(v => `${v.chatId}: ${v.invariant}`);
+        throw new Error(`State invariants violated:\n${msgs.join('\n')}`);
+    }
+}
+/**
+ * Generate all possible state/event combinations for fuzzing.
+ */
+export function generateTransitionMatrix() {
+    const modes = [ChatMode.AI_ACTIVE, ChatMode.HUMAN_ACTIVE, ChatMode.SHARED, ChatMode.ESCALATED];
+    const events = ['TAKEOVER', 'RESUME', 'SHARE', 'ESCALATE', 'CUSTOMER_MSG', 'OWNER_MSG'];
+    const matrix = [];
+    for (const from of modes) {
+        for (const event of events) {
+            let expectedMode = from;
+            let illegal = false;
+            switch (event) {
+                case 'TAKEOVER':
+                    expectedMode = ChatMode.HUMAN_ACTIVE;
+                    break;
+                case 'RESUME':
+                    expectedMode = ChatMode.AI_ACTIVE;
+                    break;
+                case 'SHARE':
+                    expectedMode = ChatMode.SHARED;
+                    break;
+                case 'ESCALATE':
+                    expectedMode = ChatMode.ESCALATED;
+                    break;
+                case 'CUSTOMER_MSG':
+                case 'OWNER_MSG':
+                    // Customer messages don't change mode; owner messages trigger auto-takeover
+                    if (event === 'OWNER_MSG' && from === ChatMode.AI_ACTIVE) {
+                        expectedMode = ChatMode.HUMAN_ACTIVE;
+                    }
+                    break;
+            }
+            matrix.push({ from, event, expectedMode, illegal: false });
+        }
+    }
+    return matrix;
+}
+//# sourceMappingURL=invariants.js.map

package/dist/chat-state/invariants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariants.js","sourceRoot":"","sources":["../../src/chat-state/invariants.ts"],"names":[],"mappings":"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"}

package/dist/chat-state/store.d.ts

@@ -0,0 +1,55 @@
+export declare enum ChatMode {
+    AI_ACTIVE = "AI_ACTIVE",
+    HUMAN_ACTIVE = "HUMAN_ACTIVE",
+    SHARED = "SHARED",
+    ESCALATED = "ESCALATED"
+}
+export interface ChatState {
+    chatId: string;
+    mode: ChatMode;
+    version: number;
+    lastEventId: string;
+    autoResumeTimeoutMs: number | null;
+    pausedByOwnerAt: number | null;
+    lastOwnerActivityAt: number | null;
+    lastUserActivityAt: number | null;
+    autoResumeAt: number | null;
+    handoffReason: string | null;
+    updatedAt: number;
+}
+export declare class ChatStateStore {
+    private db;
+    private initialized;
+    constructor();
+    private init;
+    /** Get chat state. Returns default AI_ACTIVE if not found. */
+    get(chatId: string): ChatState;
+    /** Set chat mode with optimistic concurrency. */
+    setMode(chatId: string, mode: ChatMode, expectedVersion?: number): {
+        success: boolean;
+        state: ChatState;
+    };
+    /** Put exactly one chat into human handoff. Other chats are not affected. */
+    pauseForOwner(chatId: string, timeoutMs?: number, reason?: string): ChatState;
+    /** Resume AI for exactly one chat. */
+    resumeAi(chatId: string, reason?: string): ChatState;
+    /** Record owner activity during a handoff and push auto-resume out. */
+    touchOwnerActivity(chatId: string, timeoutMs?: number): ChatState;
+    /** Record customer activity for this one chat. */
+    touchUserActivity(chatId: string): ChatState;
+    /** True only for this one chat and only after its handoff timeout passes. */
+    shouldAutoResume(chatId: string, now?: number): boolean;
+    /** Record a processed event ID (prevents replay processing). */
+    recordEvent(chatId: string, eventId: string): boolean;
+    /** Check if an event was already processed. */
+    isEventProcessed(chatId: string, eventId: string): boolean;
+    /** List all chats with their modes. */
+    listAll(): ChatState[];
+    /** Count chats by mode. */
+    countByMode(): Map<ChatMode, number>;
+    /** Delete all state for a chat. */
+    delete(chatId: string): void;
+    private ensureColumn;
+    private writeState;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/chat-state/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/chat-state/store.ts"],"names":[],"mappings":"AAWA,oBAAY,QAAQ;IAClB,SAAS,cAAc;IACvB,YAAY,iBAAiB;IAC7B,MAAM,WAAW;IACjB,SAAS,cAAc;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,qBAAa,cAAc;IACzB,OAAO,CAAC,EAAE,CAAkB;IAC5B,OAAO,CAAC,WAAW,CAAS;;IAO5B,OAAO,CAAC,IAAI;IA4BZ,8DAA8D;IAC9D,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS;IAiD9B,iDAAiD;IACjD,OAAO,CACL,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,QAAQ,EACd,eAAe,CAAC,EAAE,MAAM,GACvB;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,SAAS,CAAA;KAAE;IAQzC,6EAA6E;IAC7E,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,SAAyB,EAAE,MAAM,SAAgB,GAAG,SAAS;IAapG,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,SAAiB,GAAG,SAAS;IAY5D,uEAAuE;IACvE,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS;IAWjE,kDAAkD;IAClD,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS;IAO5C,6EAA6E;IAC7E,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,OAAO;IAK3D,gEAAgE;IAChE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAOrD,+CAA+C;IAC/C,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAK1D,uCAAuC;IACvC,OAAO,IAAI,SAAS,EAAE;IAiCtB,2BAA2B;IAC3B,WAAW,IAAI,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC;IAWpC,mCAAmC;IACnC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK5B,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,UAAU;CAkDnB"}

package/dist/chat-state/store.js

@@ -0,0 +1,220 @@
+/**
+ * Chat State Store — Source of Truth
+ *
+ * SQLite-backed per-chat state with versioning and event deduplication.
+ * Versioning prevents race condition overwrites.
+ * last_event_id prevents replay bugs on reconnect.
+ */
+import { DatabaseManager } from '../database/index.js';
+// ─── Types ───────────────────────────────────────────────────────────────────
+export var ChatMode;
+(function (ChatMode) {
+    ChatMode["AI_ACTIVE"] = "AI_ACTIVE";
+    ChatMode["HUMAN_ACTIVE"] = "HUMAN_ACTIVE";
+    ChatMode["SHARED"] = "SHARED";
+    ChatMode["ESCALATED"] = "ESCALATED";
+})(ChatMode || (ChatMode = {}));
+const DEFAULT_AUTO_RESUME_MS = Number(process.env.HANDOFF_AUTO_RESUME_MS || 60 * 60 * 1000);
+// ─── Chat State Store ────────────────────────────────────────────────────────
+export class ChatStateStore {
+    db;
+    initialized = false;
+    constructor() {
+        this.db = DatabaseManager.getInstance();
+        this.init();
+    }
+    init() {
+        if (this.initialized)
+            return;
+        const rawDb = this.db.getDb();
+        rawDb.exec(`
+      CREATE TABLE IF NOT EXISTS chat_state (
+        chat_id TEXT PRIMARY KEY NOT NULL,
+        mode TEXT NOT NULL DEFAULT 'AI_ACTIVE'
+          CHECK(mode IN ('AI_ACTIVE','HUMAN_ACTIVE','SHARED','ESCALATED')),
+        version INTEGER NOT NULL DEFAULT 0,
+        last_event_id TEXT NOT NULL DEFAULT '',
+        auto_resume_timeout_ms INTEGER,
+        paused_by_owner_at INTEGER,
+        last_owner_activity_at INTEGER,
+        last_user_activity_at INTEGER,
+        auto_resume_at INTEGER,
+        handoff_reason TEXT,
+        updated_at INTEGER NOT NULL
+      );
+    `);
+        this.ensureColumn('auto_resume_timeout_ms', 'INTEGER');
+        this.ensureColumn('paused_by_owner_at', 'INTEGER');
+        this.ensureColumn('last_owner_activity_at', 'INTEGER');
+        this.ensureColumn('last_user_activity_at', 'INTEGER');
+        this.ensureColumn('auto_resume_at', 'INTEGER');
+        this.ensureColumn('handoff_reason', 'TEXT');
+        this.initialized = true;
+    }
+    /** Get chat state. Returns default AI_ACTIVE if not found. */
+    get(chatId) {
+        const rawDb = this.db.getDb();
+        const row = rawDb.prepare('SELECT * FROM chat_state WHERE chat_id = ?').get(chatId);
+        if (!row) {
+            return {
+                chatId,
+                mode: ChatMode.AI_ACTIVE,
+                version: 0,
+                lastEventId: '',
+                autoResumeTimeoutMs: null,
+                pausedByOwnerAt: null,
+                lastOwnerActivityAt: null,
+                lastUserActivityAt: null,
+                autoResumeAt: null,
+                handoffReason: null,
+                updatedAt: Date.now(),
+            };
+        }
+        return {
+            chatId: row.chat_id,
+            mode: row.mode,
+            version: row.version,
+            lastEventId: row.last_event_id,
+            autoResumeTimeoutMs: row.auto_resume_timeout_ms,
+            pausedByOwnerAt: row.paused_by_owner_at,
+            lastOwnerActivityAt: row.last_owner_activity_at,
+            lastUserActivityAt: row.last_user_activity_at,
+            autoResumeAt: row.auto_resume_at,
+            handoffReason: row.handoff_reason,
+            updatedAt: row.updated_at,
+        };
+    }
+    /** Set chat mode with optimistic concurrency. */
+    setMode(chatId, mode, expectedVersion) {
+        const current = this.get(chatId);
+        if (expectedVersion !== undefined && expectedVersion !== current.version) {
+            return { success: false, state: current };
+        }
+        return this.writeState(chatId, { mode }, current);
+    }
+    /** Put exactly one chat into human handoff. Other chats are not affected. */
+    pauseForOwner(chatId, timeoutMs = DEFAULT_AUTO_RESUME_MS, reason = 'owner_pause') {
+        const current = this.get(chatId);
+        const now = Date.now();
+        return this.writeState(chatId, {
+            mode: ChatMode.HUMAN_ACTIVE,
+            auto_resume_timeout_ms: timeoutMs,
+            paused_by_owner_at: now,
+            last_owner_activity_at: now,
+            auto_resume_at: now + timeoutMs,
+            handoff_reason: reason,
+        }, current).state;
+    }
+    /** Resume AI for exactly one chat. */
+    resumeAi(chatId, reason = 'owner_resume') {
+        const current = this.get(chatId);
+        return this.writeState(chatId, {
+            mode: ChatMode.AI_ACTIVE,
+            auto_resume_timeout_ms: null,
+            paused_by_owner_at: null,
+            last_owner_activity_at: null,
+            auto_resume_at: null,
+            handoff_reason: reason,
+        }, current).state;
+    }
+    /** Record owner activity during a handoff and push auto-resume out. */
+    touchOwnerActivity(chatId, timeoutMs) {
+        const current = this.get(chatId);
+        const now = Date.now();
+        const effectiveTimeout = timeoutMs ?? current.autoResumeTimeoutMs ?? DEFAULT_AUTO_RESUME_MS;
+        return this.writeState(chatId, {
+            last_owner_activity_at: now,
+            auto_resume_timeout_ms: effectiveTimeout,
+            auto_resume_at: now + effectiveTimeout,
+        }, current).state;
+    }
+    /** Record customer activity for this one chat. */
+    touchUserActivity(chatId) {
+        const current = this.get(chatId);
+        return this.writeState(chatId, {
+            last_user_activity_at: Date.now(),
+        }, current).state;
+    }
+    /** True only for this one chat and only after its handoff timeout passes. */
+    shouldAutoResume(chatId, now = Date.now()) {
+        const state = this.get(chatId);
+        return state.mode === ChatMode.HUMAN_ACTIVE && !!state.autoResumeAt && now >= state.autoResumeAt;
+    }
+    /** Record a processed event ID (prevents replay processing). */
+    recordEvent(chatId, eventId) {
+        const current = this.get(chatId);
+        if (current.lastEventId === eventId)
+            return false;
+        this.writeState(chatId, { last_event_id: eventId }, current, true);
+        return true;
+    }
+    /** Check if an event was already processed. */
+    isEventProcessed(chatId, eventId) {
+        const state = this.get(chatId);
+        return state.lastEventId === eventId;
+    }
+    /** List all chats with their modes. */
+    listAll() {
+        const rawDb = this.db.getDb();
+        const rows = rawDb.prepare('SELECT * FROM chat_state ORDER BY updated_at DESC').all();
+        return rows.map((r) => ({
+            chatId: r.chat_id,
+            mode: r.mode,
+            version: r.version,
+            lastEventId: r.last_event_id,
+            autoResumeTimeoutMs: r.auto_resume_timeout_ms,
+            pausedByOwnerAt: r.paused_by_owner_at,
+            lastOwnerActivityAt: r.last_owner_activity_at,
+            lastUserActivityAt: r.last_user_activity_at,
+            autoResumeAt: r.auto_resume_at,
+            handoffReason: r.handoff_reason,
+            updatedAt: r.updated_at,
+        }));
+    }
+    /** Count chats by mode. */
+    countByMode() {
+        const rawDb = this.db.getDb();
+        const rows = rawDb.prepare('SELECT mode, COUNT(*) as cnt FROM chat_state GROUP BY mode').all();
+        const map = new Map();
+        for (const r of rows)
+            map.set(r.mode, r.cnt);
+        return map;
+    }
+    /** Delete all state for a chat. */
+    delete(chatId) {
+        const rawDb = this.db.getDb();
+        rawDb.prepare('DELETE FROM chat_state WHERE chat_id = ?').run(chatId);
+    }
+    ensureColumn(name, type) {
+        const rawDb = this.db.getDb();
+        const columns = rawDb.prepare('PRAGMA table_info(chat_state)').all();
+        if (!columns.some((c) => c.name === name)) {
+            rawDb.exec(`ALTER TABLE chat_state ADD COLUMN ${name} ${type}`);
+        }
+    }
+    writeState(chatId, patch, current = this.get(chatId), incrementFromDb = false) {
+        const rawDb = this.db.getDb();
+        const now = Date.now();
+        const versionSql = incrementFromDb ? 'chat_state.version + 1' : 'excluded.version';
+        rawDb.prepare(`
+      INSERT INTO chat_state (
+        chat_id, mode, version, last_event_id, auto_resume_timeout_ms,
+        paused_by_owner_at, last_owner_activity_at, last_user_activity_at,
+        auto_resume_at, handoff_reason, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(chat_id) DO UPDATE SET
+        mode = excluded.mode,
+        version = ${versionSql},
+        last_event_id = excluded.last_event_id,
+        auto_resume_timeout_ms = excluded.auto_resume_timeout_ms,
+        paused_by_owner_at = excluded.paused_by_owner_at,
+        last_owner_activity_at = excluded.last_owner_activity_at,
+        last_user_activity_at = excluded.last_user_activity_at,
+        auto_resume_at = excluded.auto_resume_at,
+        handoff_reason = excluded.handoff_reason,
+        updated_at = excluded.updated_at
+    `).run(chatId, patch.mode ?? current.mode, current.version + 1, patch.last_event_id ?? current.lastEventId, patch.auto_resume_timeout_ms !== undefined ? patch.auto_resume_timeout_ms : current.autoResumeTimeoutMs, patch.paused_by_owner_at !== undefined ? patch.paused_by_owner_at : current.pausedByOwnerAt, patch.last_owner_activity_at !== undefined ? patch.last_owner_activity_at : current.lastOwnerActivityAt, patch.last_user_activity_at !== undefined ? patch.last_user_activity_at : current.lastUserActivityAt, patch.auto_resume_at !== undefined ? patch.auto_resume_at : current.autoResumeAt, patch.handoff_reason !== undefined ? patch.handoff_reason : current.handoffReason, now);
+        return { success: true, state: this.get(chatId) };
+    }
+}
+//# sourceMappingURL=store.js.map