# TwinDesk (`com.intrepid.twindesk`) — Exhaustive Technical & Commercial Knowledgebase (`llms-full.txt`)

> **Canonical Product Domain**: https://twindesk.intrepidtech.net
> **Package ID**: `com.intrepid.twindesk`
> **Publisher**: Intrepid Technology (`https://dev.intrepidtech.net`, `mailto:dev@intrepidtech.net`)
> **Privacy Policy**: https://dev.intrepidtech.net/privacy-policy/
> **Live Partner Venture Production WhatsApp**: https://wa.me/923282198558 (`+92 328 2198558`)

---

## 1. Executive Architecture Overview

**TwinDesk** solves the hardest operational bottleneck in WhatsApp conversational commerce: traditional WhatsApp Cloud API bots force founders to surrender their physical WhatsApp Business phone app, while rigid button-tree chatbots alienate customers who prefer sending voice notes, asking off-menu questions, or replying mid-conversation.

TwinDesk combines **WhatsApp Business App Coexistence (`is_on_biz_app: true`)** with a **sub-2-second `gemini-3.8-flash` (`thinkingBudget: 0`)** AI Sales Twin and **12 deterministic function-calling tools**.

---

## 2. Deep Technical Specifications

### 2.1 True Mobile Coexistence & Bidirectional Echo Bus (`messages` + `smb_message_echoes`)
- **Coexistence Safety Interlock (`assertCoexistenceSafeEndpoint`)**: Strictly blocks `POST /{PHONE_NUMBER_ID}/request_code` and `POST /{PHONE_NUMBER_ID}/register` so the physical handset session is never disconnected.
- **Self-Messaging Error `131031` Prevention (`resolveStaffAlertRecipients`)**: Automatically excludes the coexistence sender phone from outbound staff alert recipients.
- **Bidirectional Outbound Echo Evaluation (`handleFounderOutboundCoexistenceEcho`)**:
  - Ignores echoes of the bot's own Cloud API replies via `botSentWamids`.
  - When the founder types on their physical phone and naturally invites the AI Twin by name, TwinDesk flips `pausedForHuman = false` (`coexistence_founder_handoff_to_twin`) and responds immediately.
  - When the founder messages a contact directly without inviting the AI Twin, TwinDesk pauses in `0ms` (`coexistence_manual_echo_paused`) and scrubs personal chat history.
- **Reply-Context Ownership Guard (`skipped_non_bot_context`)**: If a customer swipe-replies (`contextMessageId`) to a message sent manually by the human founder, the AI Twin stays silent and pauses the session.
- **Cold-Start Bare Acknowledgement Filter (`skipped_bare_ack_without_active_session`)**: Bare replies (`"k"`, `"ok"`, `"okay"`, `"done"`, `"theek hai"`, `"acha"`, `"hmm"`) arriving with no active bot conversation in the last 2 hours are ignored so the bot never cold-starts a sales pitch after a manual human chat.

### 2.2 Zero-Touch `.vcf` Personal Contact Whitelist & Privacy Auto-Purge
- **Canonical Phone Identity (`normalizePhoneIdentity`)**: Normalizes `03xx`, `923xx`, `+92 3xx`, `+92 03xx`, and `00923xx` to a canonical E.164 digit identity.
- **Step `0e` Webhook Bypass (`whitelist_bypass`)**: Personal/family contacts imported via `.vcf` vCard bundles or forwarded WhatsApp contact cards bypass LLM inference, receipt OCR, and JSONL event logging in `0ms`.
- **Personal Voice Note Guard (`silent_handoff_to_founder`)**: Personal voice notes from unknown numbers silently pause the thread (`suppressTextReply: true`) and alert the founder without replying to the sender.

### 2.3 Sub-2s Zero-Latency Conversational Brain (`gemini-3.8-flash`)
- **Active Gemini 3.x Cascade**: `gemini-3.8-flash` -> `gemini-3.7-flash` -> `gemini-3.6-flash` -> `gemini-3.5-flash` -> `gemini-3.5-flash-lite` -> `gemini-3.1-flash-lite`. Retired 404 models (`2.5-flash`, `2.0-flash`, `1.5-flash`, and on-device `gemini-nano`) are permanently blocked.
- **Prefix-Cache-Preserving Multi-Round Loop**: `thinkingConfig: { thinkingBudget: 0 }` with `systemInstruction` and `tools` hoisted once outside `while (round < 4)` so Round 1 (tool call) and Round 2 (final reply) share a 100% byte-identical prompt prefix.
- **Network & Concurrency Resilience**:
  - `NODE_OPTIONS=--dns-result-order=ipv4first` eliminates IPv6 AAAA DNS stalls in Linux containers.
  - Per-round `AbortController` timeouts (`8s` text / `15s` multimodal / `10s` Graph API) paired with a 60-second shared circuit breaker (`tripModelCircuitBreaker`).
  - 90-second webhook freshness gate (`MAX_LIVE_WEBHOOK_AGE_MS`), pre-flight `wamid` deduplication, 1500ms live burst coalescer, and per-phone turn serialization (`inFlightPhoneTurns`).

### 2.4 Multimodal Voice Notes (`audio/ogg`), 1:1 Language Mirroring & Symbol Hygiene
- **Multimodal Audio (`<= 5 MB`)**: Native `inlineData` ingestion of WhatsApp `audio/ogg; codecs=opus` voice notes in English, Urdu, and Roman Urdu.
- **1:1 Language Mirroring (`isPurelyEnglishInput` + `stripChatMarkdown`)**: Pure English callers receive 100% pure English with zero unsolicited Urdu/Roman-Urdu filler; Urdu callers receive natural conversational Roman Urdu in Latin script (`stripNonLatinScript`).
- **Symbol & Emoji Hygiene (`sanitizeMessageText`)**: Strips all outbound emojis and `U+FFFD` replacement characters while preserving inbound customer emojis in `session.history` (`cleanCustomerHistoryText`).

### 2.5 12 Function-Calling Tools, Satori 1080×1440 Bento Cards & FinTech OCR
1. `get_menu_and_schedule` — Dynamic runtime catalog, volume rewards, and cutoff-aware batch schedule.
2. `quote_delivery` — Shortest motorcycle route distance (`km`) and tier fee from `0 km` origin (rejecting bare city names).
3. `update_draft_order` — Updates cart items, fulfillment type, and payment method while rejecting placeholder names (`isPlaceholderCustomerName`).
4. `apply_welcome_free_delivery` — Turn 4+ selective hospitality free-delivery voucher (`FD-YYYY-XXXXXX`).
5. `place_whatsapp_order` — Guarded by `DELIVERY_QUOTE_CONFIRMATION_REQUIRED`, `INCOMPLETE_DELIVERY_ADDRESS`, `MISSING_CUSTOMER_NAME`, and customer hesitation detection.
6. `modify_active_order` — Edits active unfulfilled orders and re-sends the dynamic EMVCo Raast QR only if `totalAmount` changed.
7. `cancel_active_order` — Cancels unfulfilled orders while preserving unpaid status integrity.
8. `check_order_status` — Enforces caller-phone ownership (`ORDER_PHONE_MISMATCH`).
9. `send_product_photo` — Dispatches `single_piece` close-up, packaged `box` photo, or `1080×1440` Satori Light-Mode Bento `menu` card (`Outfit` `400–900` static TTF fonts, SHA-256 fingerprint invalidation, 25-day `media_id` cache, unified single-bubble image+caption delivery).
10. `react_to_customer_message` — Context-eligible native WhatsApp reactions (`evaluateReactionEligibility`).
11. `request_human_handoff` — Pauses automated replies and escalates to human staff.
12. `silent_handoff_to_founder` — Silently pauses personal/non-business threads (`suppressTextReply: true`).

### 2.6 EMVCo Raast QR, 5-Stage Receipt Verification & Rs 0 Window Router
- **Dynamic EMVCo ISO/IEC 18004 QR (`buildDynamicRaastEmvcoPayload`)**: Encodes merchant IBAN/alias, PKR currency (`586`), locked order amount, and `CRC16-CCITT` (`0x1021`) checksum.
- **5-Stage Receipt Verification (`evaluateFiveStageReceiptVerification`)**:
  1. Binary magic-bytes signature (`JPEG`, `PNG`, `WebP`, `%PDF-`, blocking SVG/XML).
  2. Authentic banking receipt UI detection (routing non-receipt customer photos back to conversational AI).
  3. Exact PKR order amount match.
  4. Beneficiary account title verification.
  5. Asia/Karachi timestamp sanity and transaction reference ID check.
- **Rs 0 Free-Window-First Outreach (`dispatchWithFreeWindowFirst`)**: Delivers free interactive messages when the 24-hour customer service window is open (`sanitizeButtonTitle` `<= 20` chars), falling back to 9 approved `v10` Restrained-Bold templates when closed. Includes a 7-guard 30-minute payment reminder (`shouldSendPaymentReminder`) with 1:45 PM PKT pre-cutoff acceleration.