andorinaai/andorina-whatsapp-agent-for-hermes/v1-5-2-beta3

flowchart TD
    %% NODE DEFINITIONS (Universal Safe Format)
    A["📱 Incoming WhatsApp Message"]
    B{"Bridge Online?"}
    IGNORE["Message lost"]
    B1{"Sender == BOT_PHONE?"}
    IGNORE2["Ignore (Bot doesn't read itself)"]
    C["Acquire Concurrent Lock (fcntl.flock)"]
    C1["hook_inbox.py: Atomic Save in inbox.json"]
    D{"Auto-Responder Away active in away.json?"}
    D1{"Sender is Bot or ADMIN_PHONE?"}
    ALERTS_CHECK{"Alerts configured in alerts.json?"}
    D2{"Cooldown OK?"}
    AWAY["send.py: Send static reply & log Cooldown"]
    ALERTS_MATCH{"Fuzzy Match OK? (Ignores accents/plurals)"}
    ALERTS_FMT["Format: 🚨 Alert of X, resolve OWNER from .env"]
    ALERTS_SEND["send.py: Forward alert to Target (Owner or Admin)"]
    PRE_LLM_HOOK["pre_llm_call hook: Executes utils/admin_cli.py check"]
    ROLE_ENV{"JID is in .env WHATSAPP_ALLOWED_USERS?"}
    ROLE_IS_OWNER["Assign Role: owner (Highest Priority)"]
    ROLE_JSON{"Search JID in guard_rules.json"}
    ROLE_SPECIFIC["Assign Role: Specific JSON role"]
    ROLE_DEFAULT["Assign Role: global_default_role"]
    BLOCKED_CHECK{"Role == Blocked?"}
    REJECT_1["Block: Silently ignored"]
    CHATBOT{"Global Chatbot Enabled? (chatbot.json)"}
    REJECT_2["Block: Chatbot disabled"]
    MUTE{"JID Muted? (chatbot.json)"}
    REJECT_3["Block: User muted"]
    IS_OWNER{"Is Owner? (Highest Authority)"}
    BUILD_CONTEXT["Bypass Limits to Build Context"]
    CHECKS{"Apply Security Filters and Limits"}
    CHECK_MEDIA{"Is it Text only?"}
    REJECT_4["Block: Unsupported multimedia"]
    CHECK_LEN{"Length < MAX_CHARS_INPUT?"}
    REJECT_5["Block: Message too long"]
    CHECK_GROUP{"If group, has Wake Word?"}
    REJECT_6["Block: Group ignored"]
    CHECK_REGEX{"Contains Injection or Dangerous Regex?"}
    REJECT_7["Block: Destructive pattern detected"]
    CHECK_RATE{"Exceeds Hourly Rate Limit or in Cooldown?"}
    REJECT_8["Block: Rate Limit or Spam"]
    REG_RATE["Log message in rate_limits.json"]
    LOAD_SOUL{"Personality Waterfall (Sub-Soul)"}
    SOUL_1{"custom_soul in JSON?"}
    SOUL_CUSTOM["Load custom_soul"]
    SOUL_2{"Exists JID.md?"}
    SOUL_JID["Load JID.md"]
    SOUL_3{"Exists _default.md?"}
    SOUL_DEF["Load _default.md"]
    SOUL_HARD["Load Hardcoded text (Fallback)"]
    LOAD_NOTES_HOOK["Load Notes (notes/JID.md if exists)"]
    INJECT_1{"Permissions are 'all'?"}
    INJ_PERMS["Inject: USER PERMISSIONS"]
    INJECT_2{"Folders Restriction?"}
    INJ_FOLDERS["Inject: ALLOWED FOLDERS"]
    INJECT_3{"Contacts/Tags Restriction?"}
    INJ_TAGS["Inject: ALLOWED CONTACTS"]
    INJECT_4{"History/Chats Restriction?"}
    INJ_CHATS["Inject: ALLOWED CHATS"]
    LLM_EXEC["🤖 Hermes LLM Agent Execution"]
    MEM_CHECK{"Detects new important long-term facts?"}
    MEM_SAVE["Proactively trigger contacts.py note-add/section-set"]
    TOOL_REQ{"Does Agent launch a Tool (run_command)?"}
    SEND_REPLY["Reply in WhatsApp via Hermes. End."]
    PRE_TOOL["pre_tool_call hook: Executes utils/admin_cli.py check-tool"]
    CHECK_FLAG_INJECT{"LLM attempts to inject security flags? (--filter-chats, etc)"}
    DENY_FLAG["❌ Deny: Security evasion attempt detected"]
    PARSE_CMD{"Parse Andoriña Script and Sub-command"}
    DENY_SYS["❌ Deny: System commands forbidden"]
    MAP_PERM{"Map Command to Specific Permission"}
    MAP_DETAILS["(files.py --voice to send_voice, diag.py to run_diag, etc.)"]
    CHECK_ALL{"Does Role have global 'all' permission?"}
    TOOL_EXEC_BYPASS["✅ Execute (Owner Bypass: Skips extra validations)"]
    CHECK_PERM{"Does Role have the exact required permission?"}
    DENY_PERM["❌ Deny: Insufficient RBAC permissions"]
    CHECK_EXTRA{"Granular Validations and Scopes Injection"}
    VAL_FILES{"Absolute path is within allowed_folders?"}
    TOOL_EXEC["✅ Execute Andoriña Script with Injected Security"]
    VAL_TAGS{"Silently inject flag --filter-tags"}
    CONTACTS_EXEC{"Search fails in local cache?"}
    OAUTH_REFRESH["Google OAuth Auto-Refresh and retry"]
    VAL_CHATS{"Inject flag --filter-chats (Resolves 'self' to JID)"}
    VAL_AGENDA{"Silently inject flag --creator-jid"}
    FAKE_TYPING["Simulate 'Typing...' (time.sleep of 1.5s - 5s)"]
    SELF_LOG["common.py: log_outgoing()"]
 
    %% EDGES (IDs Only)
    A --> B
    B -->|No| IGNORE
    B -->|Yes| B1
    B1 -->|Yes| IGNORE2
    B1 -->|No| C
    C --> C1
    C1 --> D
    D -->|Yes| D1
    D1 -->|Yes| ALERTS_CHECK
    D1 -->|No| D2
    D2 -->|Yes| AWAY
    AWAY --> ALERTS_CHECK
    D2 -->|No or In Cooldown| ALERTS_CHECK
    D -->|No| ALERTS_CHECK
    ALERTS_CHECK -->|Yes| ALERTS_MATCH
    ALERTS_MATCH -->|Yes| ALERTS_FMT
    ALERTS_FMT --> ALERTS_SEND
    ALERTS_MATCH -->|No| PRE_LLM_HOOK
    ALERTS_SEND --> PRE_LLM_HOOK
    ALERTS_CHECK -->|No| PRE_LLM_HOOK
    PRE_LLM_HOOK --> ROLE_ENV
    ROLE_ENV -->|Yes| ROLE_IS_OWNER
    ROLE_ENV -->|No| ROLE_JSON
    ROLE_JSON -->|Found| ROLE_SPECIFIC
    ROLE_JSON -->|Not Found| ROLE_DEFAULT
    ROLE_IS_OWNER --> BLOCKED_CHECK
    ROLE_SPECIFIC --> BLOCKED_CHECK
    ROLE_DEFAULT --> BLOCKED_CHECK
    BLOCKED_CHECK -->|Yes| REJECT_1
    BLOCKED_CHECK -->|No| CHATBOT
    CHATBOT -->|No| REJECT_2
    CHATBOT -->|Yes| MUTE
    MUTE -->|Yes| REJECT_3
    MUTE -->|No| IS_OWNER
    IS_OWNER -->|Yes| BUILD_CONTEXT
    IS_OWNER -->|No| CHECKS
    CHECKS --> CHECK_MEDIA
    CHECK_MEDIA -->|No| REJECT_4
    CHECK_MEDIA -->|Yes| CHECK_LEN
    CHECK_LEN -->|No| REJECT_5
    CHECK_LEN -->|Yes| CHECK_GROUP
    CHECK_GROUP -->|No| REJECT_6
    CHECK_GROUP -->|Yes| CHECK_REGEX
    CHECK_REGEX -->|Yes| REJECT_7
    CHECK_REGEX -->|No| CHECK_RATE
    CHECK_RATE -->|Yes| REJECT_8
    CHECK_RATE -->|No| REG_RATE
    REG_RATE --> BUILD_CONTEXT
    BUILD_CONTEXT --> LOAD_SOUL
    LOAD_SOUL --> SOUL_1
    SOUL_1 -->|Yes| SOUL_CUSTOM
    SOUL_1 -->|No| SOUL_2
    SOUL_2 -->|Yes| SOUL_JID
    SOUL_2 -->|No| SOUL_3
    SOUL_3 -->|Yes| SOUL_DEF
    SOUL_3 -->|No| SOUL_HARD
    SOUL_CUSTOM --> LOAD_NOTES_HOOK
    SOUL_JID --> LOAD_NOTES_HOOK
    SOUL_DEF --> LOAD_NOTES_HOOK
    SOUL_HARD --> LOAD_NOTES_HOOK
    LOAD_NOTES_HOOK --> INJECT_1
    INJECT_1 -->|No| INJ_PERMS
    INJECT_1 -->|Yes| INJECT_2
    INJ_PERMS --> INJECT_2
    INJECT_2 -->|Yes| INJ_FOLDERS
    INJECT_2 -->|No| INJECT_3
    INJ_FOLDERS --> INJECT_3
    INJECT_3 -->|Yes| INJ_TAGS
    INJECT_3 -->|No| INJECT_4
    INJ_TAGS --> INJECT_4
    INJECT_4 -->|Yes| INJ_CHATS
    INJECT_4 -->|No| LLM_EXEC
    INJ_CHATS --> LLM_EXEC
    LLM_EXEC --> MEM_CHECK
    MEM_CHECK -->|Yes| MEM_SAVE
    MEM_SAVE --> PRE_TOOL
    MEM_CHECK -->|No| TOOL_REQ
    TOOL_REQ -->|No| SEND_REPLY
    TOOL_REQ -->|Yes| PRE_TOOL
    PRE_TOOL --> CHECK_FLAG_INJECT
    CHECK_FLAG_INJECT -->|Yes| DENY_FLAG
    CHECK_FLAG_INJECT -->|No| PARSE_CMD
    PARSE_CMD -->|System or Unauthorized| DENY_SYS
    PARSE_CMD --> MAP_PERM
    MAP_PERM --> MAP_DETAILS
    MAP_DETAILS --> CHECK_ALL
    CHECK_ALL -->|Yes| TOOL_EXEC_BYPASS
    CHECK_ALL -->|No| CHECK_PERM
    CHECK_PERM -->|No| DENY_PERM
    CHECK_PERM -->|Yes| CHECK_EXTRA
    CHECK_EXTRA -->|files.py| VAL_FILES
    VAL_FILES -->|Traversal Fail or Out of Bounds| DENY_PERM
    VAL_FILES -->|OK| TOOL_EXEC
    CHECK_EXTRA -->|contacts.py search| VAL_TAGS
    VAL_TAGS --> CONTACTS_EXEC
    CONTACTS_EXEC -->|Yes| OAUTH_REFRESH
    CONTACTS_EXEC -->|No| TOOL_EXEC
    OAUTH_REFRESH --> TOOL_EXEC
    CHECK_EXTRA -->|inbox.py read/search/list| VAL_CHATS
    VAL_CHATS --> TOOL_EXEC
    CHECK_EXTRA -->|agenda.py| VAL_AGENDA
    VAL_AGENDA --> TOOL_EXEC
    CHECK_EXTRA -->|Admin Commands| TOOL_EXEC
    CHECK_EXTRA -->|alerts.py| TOOL_EXEC
    CHECK_EXTRA -->|send.py message/broadcast| FAKE_TYPING
    FAKE_TYPING --> TOOL_EXEC
    TOOL_EXEC_BYPASS -.->|If send.py or files.py executes successfully| SELF_LOG
    TOOL_EXEC -.->|If send.py or files.py executes successfully| SELF_LOG
    SELF_LOG -.->|Injects bot reply into history with origin Me| C1