feat(gateway): implement hybrid LINE reply/push strategy

[iamninihuang]

Problem

The current LINE gateway implementation relies solely on the Push Message API. This consumes the monthly free quota (typically 200 messages) very quickly, making it unsuitable for active bots.

Solution

Implemented a stateful hybrid messaging strategy in the gateway:

• Reply Token Caching: Webhook events capture replyToken and store them in a thread-safe memory cache (TTL 50s, max 10k entries).
• Hybrid Dispatch: Prioritizes the free Reply API; falls back to Push API if the token is missing or expired.
• Duplicate Safety: Non-token-specific errors (5xx, network) do NOT fall back to Push to avoid duplicate delivery.
• Cache Sweep: Background task cleans expired entries every 50s.

Design

LINE User sends message
        │
        ▼
┌─────────────────────────────────────────────────────┐
│  Gateway: POST /webhook/line                        │
│                                                     │
│  1. Verify HMAC signature                           │
│  2. Generate event_id = "evt_<uuid>"                │
│  3. Cache: event_id → (replyToken, timestamp)       │
│  4. Send GatewayEvent { event_id } to OAB via WS    │
└──────────────────────┬──────────────────────────────┘
                       │ WebSocket
                       ▼
┌─────────────────────────────────────────────────────┐
│  OAB Core                                           │
│                                                     │
│  1. Receive GatewayEvent                            │
│  2. Store event_id in ChannelRef.origin_event_id    │
│     (#619)                                          │
│  3. Process message → agent generates response      │
│  4. send_message() builds GatewayReply:             │
│     reply_to = origin_event_id = "evt_<uuid>"       │
└──────────────────────┬──────────────────────────────┘
                       │ WebSocket
                       ▼
┌─────────────────────────────────────────────────────┐
│  Gateway: Hybrid Dispatch                           │
│                                                     │
│  reply.reply_to = "evt_<uuid>"                      │
│       │                                             │
│       ▼                                             │
│  cache.remove("evt_<uuid>")                         │
│       │                                             │
│       ├── HIT + fresh (< 50s)                       │
│       │     └─→ LINE Reply API (FREE) ✅             │
│       │           │                                 │
│       │           ├── 200 OK → done                 │
│       │           ├── 400 token unusable → Push ↓   │
│       │           └── 5xx/network → do NOT Push ⚠️  │
│       │                                             │
│       ├── HIT + expired (> 50s)                     │
│       │     └─→ Push API (quota) ↓                  │
│       │                                             │
│       └── MISS (no token cached)                    │
│             └─→ Push API (quota) ↓                  │
│                                                     │
│  Push API: POST v2/bot/message/push                 │
│  (fallback, consumes monthly quota)                 │
└─────────────────────────────────────────────────────┘

Core dependency

Requires PR #619 (merged) which propagates event_id through ChannelRef.origin_event_id to GatewayReply.reply_to, enabling the gateway to correlate replies with cached reply tokens.

Review fixes applied

• Fixed operator precedence bug in Reply API 400 fallback logic
• Changed lock().unwrap() to lock().unwrap_or_else(|e| e.into_inner()) for mutex poison safety
• Added cache size bound (10k max) to prevent unbounded memory growth
• Removed docs/feature-requests/line-reply-api.md (feature is shipped, ADR covers it)

Closes #607

https://discord.com/channels/1491295327620169908/1491365150664560881/1498518933198737429

[shaun-agent]

PR #608 Screening

Verdict: changes requested / do not merge yet.

PR: #608
Reference PR checked: #492

---

Findings

Blocker: replies can attach to the wrong LINE message under same-channel concurrency.

gateway/src/main.rs:452 auto-fills empty reply_to from the last event seen for that channel. But normal gateway sends still emit empty reply_to in src/gateway.rs:139, while inbound trigger state only preserves message_id, not event_id, at src/gateway.rs:382.

If two LINE messages arrive in the same group/user before the first agent reply returns, the first reply can consume the second message's reply token. That is a real correctness bug. The fix should carry explicit per-message reply context through the adapter, not infer it from "latest event".

---

Major: cache mutex is held across the LINE Reply API network call.

gateway/src/main.rs:581 locks reply_cache, removes the entry, then awaits .send() before the lock scope ends. That serializes all token cache access behind a network request, including webhook-side inserts. Remove the cache entry into a local variable, drop the lock, then call LINE.

---

Security/process footgun: run_gateway.sh introduces secrets.env, but it is not ignored.

run_gateway.sh:9 sources secrets.env; .gitignore does not ignore it. Either remove this local helper from the PR, move it under docs/examples, or add secrets.env to .gitignore.

---

Formatting fails on the changed gateway file.

rustfmt --edition 2021 --check gateway/src/main.rs reports diffs in the new code. Small, but should be fixed before merge.

[chaodu-agent]

⚠️ Core Dependency: reply_to is always empty

We traced the full data flow and found that OAB core's send_message in src/gateway.rs currently hardcodes reply_to: String::new():

// src/gateway.rs — GatewayAdapter::send_message
let reply = GatewayReply {
    reply_to: String::new(),   // ← always empty
    ...
};

The event_id field on GatewayEvent is even marked #[allow(dead_code)] — it is never read or propagated.

This means the reply token cache in this PR will never hit. cache.remove(&reply.reply_to) is always cache.remove(""), which always misses, so every reply falls back to Push API. The hybrid feature is effectively a no-op today.

What core needs to do

1. Remove #[allow(dead_code)] from GatewayEvent.event_id
2. Propagate event_id through the message handling chain (e.g. add origin_event_id: Option<String> to ChannelRef or MessageRef)
3. Fill reply_to with the originating event_id in send_message

Suggestion

Please update the PR description to note this dependency explicitly, and open a tracking issue for the core-side change. The gateway-side cache logic looks correct and will work once core carries reply_to through — but reviewers and users should know this feature is pending core support before it becomes functional.

---

Review by 超渡法師 🙏