nduka 1.0.0

package/README.md

@@ -0,0 +1,157 @@
+# WhatsApp AI Gateway
+
+Production-ready WhatsApp AI Gateway built on Baileys.
+
+Current release:
+
+```text
+chatbot-v2-tool-system
+```
+
+Active feature branch:
+
+```text
+work/v2-async-safety-and-docs
+```
+
+Stacked on:
+
+```text
+main
+```
+
+Release verification baseline:
+
+```text
+75 test files passed
+659 tests passed
+Docker runtime reached READY
+Manual local WhatsApp smoke passed
+Manual Docker WhatsApp smoke passed
+```
+
+## Documentation
+
+Read these in order:
+
+1. `docs/installation.md` for setup, configuration, testing, local runtime, Docker runtime, and troubleshooting.
+2. `docs/production-handover.md` for release handover, production checks, regression map, and branch cleanup.
+3. `docs/async-job-workflow.md` for the durable async job design and the rule that delayed replies require persisted jobs.
+4. `docs/tool-configuration-guide.md` for accepted tool JSON formats, routing metadata, schema options, access rules, and tool testing.
+5. `docs/config-write-commands.md` for v2.2 safe config mutation commands.
+6. `docs/production-monitoring.md` for v2.6 runtime health, Docker healthcheck, log rotation, and data backup/restore.
+7. `docs/baileys-resilience.md` for v2.7 reconnect/session resilience.
+8. `docs/docker.md` for Docker-specific notes.
+9. `docs/npm-install.md` for global CLI package checks.
+10. `docs/connector-implementation-playbook.md` for future connector guidance.
+
+## Quick local verification
+
+```bash
+npm install
+npm run build
+npm test
+npm run cli -- doctor
+npm run cli -- smoke
+npm run cli -- config validate
+npm run cli -- health
+```
+
+Expected release baseline:
+
+```text
+75 test files passed
+659 tests passed
+```
+
+## Config write commands
+
+The v2.2 branch adds safe writes for `config/chatbot.config.json` only:
+
+```bash
+npm run cli -- config set <path> <json-value>
+npm run cli -- config unset <path>
+npm run cli -- config backup
+npm run cli -- config restore <backup-file>
+npm run cli -- config diff
+npm run cli -- config validate
+```
+
+Config writes create backups, validate before saving, reject unsafe paths, reject secret-like values, and leave `config/tools.chatbot.json` read-only for this milestone.
+
+## Production monitoring commands
+
+The v2.6 branch adds health and runtime data operations:
+
+```bash
+npm run cli -- health
+npm run cli -- health --quiet
+bash scripts/backup-data.sh
+bash scripts/restore-data.sh <backup-file> --yes
+bash scripts/check-runtime.sh
+```
+
+Docker healthchecks now use the real CLI health command, and Compose includes bounded log files.
+
+## Baileys resilience
+
+The v2.7 branch strengthens reconnect behavior:
+
+- Bad sessions are treated as terminal instead of reconnect-looping.
+- Terminal disconnects clear pending reconnect timers.
+- Repeated reconnect schedules trigger a rapid-loop pause.
+- Restart-required events still reconnect immediately unless the rapid-loop circuit breaker is active.
+
+Run the targeted reconnect test:
+
+```bash
+npm test -- src/gateway/reconnect/__tests__/manager.test.ts
+```
+
+## Local runtime
+
+```bash
+npm run start:worker
+```
+
+Wait for:
+
+```text
+READY — processing messages now
+```
+
+## Docker runtime
+
+```bash
+docker compose down
+docker compose build --no-cache
+docker compose run --rm wa-chatbot node dist/cli/index.js doctor
+docker compose run --rm wa-chatbot node dist/cli/index.js config validate
+docker compose run --rm wa-chatbot node dist/cli/index.js health
+docker compose run --rm wa-chatbot node dist/cli/index.js smoke
+docker compose up
+```
+
+Stop Docker:
+
+```bash
+docker compose down
+```
+
+## Release-critical behavior
+
+- Owner diagnostics and tool commands work in owner self-chat.
+- Normal user chats receive normal user-facing replies.
+- Natural-language current-information questions can route through tools when needed.
+- Group replies follow configured activation rules.
+- Docker persists auth, database, and media in `./data` and mounts config read-only from `./config`.
+- AI replies are sanitized before WhatsApp output so model preambles and tool artifacts are not sent to users.
+- Health checks must not start WhatsApp, pair WhatsApp, or send messages.
+- Reconnect logic must not loop forever after bad session, logout, device removal, connection replacement, forbidden, or multi-device mismatch.
+
+## Future work not included in the v2 release tag
+
+- Arbitrary custom HTTP tool execution.
+- npm publishing.
+- Additional provider fallback tuning for weak web/news results.
+- Custom tool connector system.

package/config/agent-tools.settings.json

@@ -0,0 +1,70 @@
+{
+  "version": 1,
+  "planner": {
+    "promptName": "agent_tool_planner",
+    "llmTask": "classification",
+    "suppressThinking": true,
+    "sanitizeResponse": false,
+    "weakRetry": false,
+    "maxTokens": 900,
+    "temperature": 0,
+    "timeoutMs": 35000,
+    "repairAttempts": 2
+  },
+  "candidateDetector": {
+    "maxCandidates": 5,
+    "minScore": 3,
+    "normalChatPatterns": [
+      "\\b(do you remember|remember when|what did i tell you|what did we discuss|what did i say|earlier in this chat|previously told you)\\b",
+      "\\b(rewrite|rephrase|make this|write this|draft|proofread|translate|summarize this message)\\b",
+      "\\b(thanks|thank you|okay|ok|yes|no|cool|great)\\b"
+    ],
+    "toolNeedPatterns": [
+      "\\b(latest|current|today|right now|recent|newest|this week|this month|live|updated)\\b",
+      "\\b(search|look up|lookup|find online|check online|fetch|open the link|visit the link|verify|source)\\b",
+      "https?:\\/\\/"
+    ],
+    "followupPatterns": [
+      "\\b(what about|how about|and the|the other one|that one|this one|it|that|those|second one|first one|open it|open that|fetch it|summarize it|summarize that|compare them|is that still true)\\b",
+      "\\b(try again|retry|rerun|run it again|do it again|check.*again|search.*again|look.*again)\\b"
+    ],
+    "contextAnswerPatterns": [
+      "\\b(explain|simpler|break it down|talk about|discuss|yarn|gist)\\b",
+      "\\b(what does (this|that|it) mean|what.*mean|wetin.*mean|this one mean|that one mean)\\b",
+      "\\b(what.*issue|wetin.*issue|wetin dem say|so wetin dem say|make we yarn|this one tough|that one tough)\\b"
+    ],
+    "forceLookupPatterns": [
+      "\\b(search|look up|lookup|find online|check online|check first|check am|verify|confirm|source)\\b",
+      "\\b(latest|current|today|right now|recent|newest|this week|this month|live|updated)\\b",
+      "\\b(appointed|appoint|take over|successor|new leader|government|govt|official|authority|authorities)\\b",
+      "https?:\\/\\/",
+      "\\b(try again|retry|rerun|check.*again|search.*again|look.*again)\\b"
+    ],
+    "openOrFetchPattern": "\\b(open|fetch|visit|read the link|go to)\\b",
+    "summarizeOrComparePattern": "\\b(summarize|compare|explain|simpler|shorter|what does it mean)\\b",
+    "sameToolFollowupPattern": "\\b(what about|how about|still|latest|current|today|tomorrow|saturday|sunday|monday|tuesday|wednesday|thursday|friday|try again|retry|rerun|run it again|do it again)\\b|\\b(check|search|look)\\b.*\\bagain\\b"
+  },
+  "context": {
+    "recentLimit": 10,
+    "summaryMaxLength": 4000,
+    "previewMaxLength": 4000
+  },
+  "chain": {
+    "maxSteps": 2,
+    "readOnlyOnly": true,
+    "parallelEnabled": false
+  },
+  "mcp": {
+    "maxDescriptionLength": 1200,
+    "metadataRiskPatterns": [
+      "ignore previous",
+      "ignore all",
+      "system prompt",
+      "developer message",
+      "exfiltrate",
+      "secret",
+      "api key",
+      "token"
+    ]
+  }
+}

package/config/chatbot.config.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "./chatbot.config.schema.json",
+  "version": 1,
+  "chatbot": {
+    "mode": "customer-chat",
+    "ownerOnlyCommands": true,
+    "usersCanOnlyChat": true
+  },
+  "channels": {
+    "whatsapp": {
+      "enabled": true,
+      "dmPolicy": "open",
+      "allowFrom": [
+        "*"
+      ],
+      "groupPolicy": "open",
+      "groupAllowFrom": [
+        "*"
+      ],
+      "selfChatMode": true,
+      "groups": {
+        "*": {
+          "enabled": true,
+          "activation": "mention",
+          "unmentionedInbound": "store_only",
+          "historyLimit": 50,
+          "mentionPatterns": [
+            "@?bot",
+            "@?assistant"
+          ],
+          "allowMediaWhenMentioned": true
+        }
+      }
+    }
+  },
+  "tools": {
+    "enabled": true,
+    "autoToolsInChat": false,
+    "profile": "chatbot",
+    "allow": [
+      "web_search",
+      "news_search",
+      "url_fetch",
+      "vision_ocr",
+      "pdf_summary"
+    ],
+    "denyHighRiskTools": true,
+    "web": {
+      "search": {
+        "enabled": true,
+        "provider": "crunchtrova",
+        "fallbackProviders": [
+          "news"
+        ],
+        "maxResults": 5,
+        "timeoutSeconds": 180,
+        "cacheTtlMinutes": 15,
+        "queryRewrite": "conservative"
+      },
+      "news": {
+        "enabled": true,
+        "provider": "crunchtrova",
+        "fallbackProviders": [],
+        "maxResults": 5,
+        "timeoutSeconds": 180,
+        "cacheTtlMinutes": 15,
+        "queryRewrite": "conservative",
+        "stripDateForNews": true
+      },
+      "fetch": {
+        "enabled": true,
+        "provider": "crunchtrova",
+        "fallbackProviders": [],
+        "maxResults": 1,
+        "timeoutSeconds": 180,
+        "contentLimit": 1500
+      }
+    },
+    "media": {
+      "image": {
+        "enabled": true,
+        "timeoutSeconds": 180,
+        "primary": {
+          "provider": "gemini",
+          "model": "gemini-3.5-flash"
+        }
+      },
+      "pdf": {
+        "enabled": true,
+        "timeoutSeconds": 180,
+        "primary": {
+          "provider": "gemini",
+          "model": "gemini-3.5-flash"
+        }
+      },
+      "audio": {
+        "enabled": true,
+        "provider": "groq",
+        "model": "whisper-large-v3"
+      }
+    },
+    "ownerToolCommands": true,
+    "asyncJobs": {
+      "enabled": true
+    }
+  },
+  "debug": {
+    "traceRouting": true,
+    "traceTools": true,
+    "traceMedia": true,
+    "redactSecrets": true
+  }
+}

package/config/chatbot.config.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "WhatsApp Chatbot Config",
+  "type": "object",
+  "required": ["version", "chatbot", "channels", "tools", "debug"],
+  "properties": {
+    "version": { "type": "number" },
+    "chatbot": {
+      "type": "object",
+      "required": ["mode", "ownerOnlyCommands", "usersCanOnlyChat"],
+      "properties": {
+        "mode": { "const": "customer-chat" },
+        "ownerOnlyCommands": { "type": "boolean" },
+        "usersCanOnlyChat": { "type": "boolean" }
+      }
+    },
+    "channels": {
+      "type": "object",
+      "required": ["whatsapp"],
+      "properties": {
+        "whatsapp": {
+          "type": "object",
+          "required": ["enabled", "dmPolicy", "allowFrom", "groupPolicy", "groupAllowFrom", "groups"],
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "dmPolicy": { "enum": ["open", "allowlist", "disabled"] },
+            "allowFrom": { "type": "array", "items": { "type": "string" } },
+            "groupPolicy": { "enum": ["open", "allowlist", "disabled"] },
+            "groupAllowFrom": { "type": "array", "items": { "type": "string" } },
+            "selfChatMode": { "type": "boolean" },
+            "groups": {
+              "type": "object",
+              "required": ["*"],
+              "additionalProperties": {
+                "type": "object",
+                "required": ["enabled", "activation", "unmentionedInbound", "historyLimit", "mentionPatterns", "allowMediaWhenMentioned"],
+                "properties": {
+                  "enabled": { "type": "boolean" },
+                  "activation": { "enum": ["off", "mention", "always"] },
+                  "unmentionedInbound": { "enum": ["store_only", "drop"] },
+                  "historyLimit": { "type": "number", "minimum": 1, "maximum": 500 },
+                  "mentionPatterns": { "type": "array", "items": { "type": "string" } },
+                  "allowMediaWhenMentioned": { "type": "boolean" }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "tools": { "type": "object" },
+    "debug": { "type": "object" }
+  }
+}

package/config/connectors.chatbot.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "enabled": false,
+  "connectors": []
+}