WhatsApp as a bridge

1Why move at all

WhatsApp is the oldest SmolPaws channel, and it shows: it lives in the repository root (src/index.ts), it boots as the app itself, and it predates the bridge abstraction the newer channels use. Every other channel — Discord, Slack, email — is an apps/<name> plugin that the host starts and stops independently. WhatsApp is the exception, and being the exception is now the problem.

Two forces make this a P0:

• The cutover to the new transpiled stack. We are proving the new TypeScript OpenHands agent-server with Slack (paws) as the guinea pig. When it is proven, the primary channel has to follow — but only if WhatsApp can talk to that server the same durable way Slack does.
• One shape, many front doors. When WhatsApp is a bridge like the others, the whole system has one mental model: a thin front door per platform, one durable relay, one agent-server. Less bespoke code to reason about, and the eight-minute-understandable property survives.

2WhatsApp today

The current channel is a Baileys multi-device client wrapped in a poll loop, with a set of concerns that the thin bridges simply do not carry. From src/:

The important detail: WhatsApp already has a durable SQLite store and a coordinator. It is not starting from nothing — it is on the legacy dispatch path (the older turnClient / /turns route into the agent-server), while Slack has already moved to the durable Message Relay.

3The Slack pattern (the target we copy)

Slack (apps/slack, the live paws app) is kind: standalone. It deliberately does not use BaseBridgeAdapter, bridgeRegistry, turnClient, or /turns. It runs as its own process and drives the durable relay directly. Its own AGENTS.md is blunt about it:

Slack Socket Mode
  -> SlackBridge / slackHandler
  -> SlackRelayRuntime.accept()
  -> MessageRelay durable intake (SQLite)
  -> TypeScript OpenHands agent-server (:8790)
  -> agent EventLog
  -> OutboundRelay.syncDeliveryOutbox()
  -> durable delivery outbox
  -> DeliveryDispatcher
  -> SlackDeliveryTarget
  -> chat.postMessage

The relay pieces are shared code in src/coordinator/, not Slack-specific:

4Target: apps/whatsapp

Mirror the Slack layout. Same file names, WhatsApp guts.

apps/whatsapp/
  plugin.json         # kind: "standalone"  (NOT loaded by the bridge loader)
  package.json
  src/
    index.ts          # process entry: wire config -> runtime -> start
    config.ts         # env + ~/.smolpaws paths, allowlist, relay server URL
    adapter.ts        # WhatsAppBridge: owns the Baileys connection + poll loop
    handler.ts        # trigger logic, scope resolution, media -> IncomingMessage
    relayRuntime.ts   # WhatsAppRelayRuntime: intake + outbound workers
    deliveryTarget.ts # WhatsAppDeliveryTarget: Baileys sendMessage / media
    __tests__/

The plugin.json mirrors Slack's, declaring kind: "standalone" so the bridge loader ignores it (the loader only auto-starts kind: "bridge" manifests). WhatsApp is started on its own, like paws.

5What must not be lost

The enyst.io WhatsApp page already names why WhatsApp never became a bridge: it "carries concerns the bridges don't: the SQLite store, the scope/permission model, the scheduler, and media pipelines." Those concerns are the acceptance criteria for this rewrite. Nothing here gets dropped — it gets rehomed into apps/whatsapp.

6The relay flow

Durable boundaries carry over directly from the Slack design: coordinator SQLite keyed by the stable WhatsApp message identity is the idempotency authority; a process-local dedup gate is only a short-lived optimization and never the source of truth. Once a delivery row is marked send_attempted, a failure is delivery_unknown — never blindly re-send a message that may already have landed. WhatsApp gets its own versioned relay DB and conversation namespace (e.g. whatsapp-relay:v1); it must not reuse legacy conversation IDs, or it could rediscover and re-send historical replies.

7Start like a bridge, not like the app

Today WhatsApp boots because it is src/index.ts — the thing you run. After the move, the host starts apps/whatsapp as a separate process, the same way paws is started:

./scripts/run-local-smolpaws.sh npm --prefix apps/whatsapp run start

This is the one intended behavioral difference Engel called out. It also unlocks the operational wins: WhatsApp can be restarted without touching the agent-server, it can run against a local or remote agent-server by config, and the repo root stops being a single channel's home.

8Migration plan

1. Prerequisite. The new agent-server is proven by paws end-to-end (epic smolpaws-zlo, blocked-by smolpaws-b1r and smolpaws-c6q).
2. Scaffold apps/whatsapp from the Slack layout — plugin.json, config.ts, empty runtime/target with tests.
3. Lift the front door. Move connect/poll/reconnect into adapter.ts; move trigger + scope + media into handler.ts; move send into deliveryTarget.ts. No behavior change.
4. Wire the relay. Copy relayRuntime.ts from Slack, point it at the WhatsApp delivery target and a fresh whatsapp-relay:v1 coordinator DB.
5. Resolve the scheduler. Decide keep-local vs lift-to-shared; wire scheduled prompts as synthetic intakes.
6. Prove it locally with the same six-point canary Slack uses: ingress accepted → intake row → agent run → outbox row → dispatcher settled → reply in the right chat. A visible reply alone is not a pass.
7. Add to the live test queue for the running smolpaws, behind the current channel, until confidence is high.
8. Cut over the live primary channel; keep the old root path as a documented rollback until the bridge has soaked.

9Risks & open questions