feat(gateway): support [[reply_to]] directive for gateway platforms

[wangyuyan-agent]

Summary

Extends the gateway protocol to support agent-controlled reply-to (#777). When an agent outputs [[reply_to:message_id]], the gateway now sends the message as a native reply/quote on the platform. Feishu is the first gateway platform to implement this — showing the native quote reference UI.

Agent output: [[reply_to:om_xxx]]\nReply content...
    │
    ▼
Core: parse_output_directives() → reply_to = "om_xxx"
    │  adapter.send_message_with_reply(channel, text, "om_xxx")
    ▼
GatewayAdapter: GatewayReply { quote_message_id: Some("om_xxx") }
    │
    ▼ WebSocket
Gateway feishu adapter: handle_reply()
    │  reply_target = quote_message_id.or(thread_id)
    ▼
Feishu Reply API: POST /im/v1/messages/om_xxx/reply → native quote UI

⚠️ Dependency

Builds on #777 (agent-controlled reply-to via [[reply_to:message_id]] directive).

Prior Art

Platform	Mechanism	Agent-Controlled?
OpenClaw	replyToMode: "off"/"first"/"all" (config)	❌ Platform decides
Hermes Agent	DISCORD_REPLY_TO_MODE env var	❌ Platform decides
OAB Discord (#777)	[[reply_to:message_id]] directive	✅ Agent chooses any message
OAB Gateway (this PR)	Same directive, via quote_message_id protocol field	✅ Agent chooses any message

Design Trade-offs

Why a new quote_message_id field?

Existing reply_to has overloaded semantics (LINE event_id / edit message_id). A dedicated field is explicit and self-documenting.

Why fallback on failure?

Discord's send_message_with_reply falls back to plain send on invalid message_id. We match this behavior — if Feishu Reply API fails, retry as plain send.

Why refactor to send_gateway_reply helper?

send_message and send_message_with_reply differed by one field. Extracted a private helper to eliminate ~35 lines of duplication.

Changes

• src/gateway.rs: Add quote_message_id to GatewayReply; refactor send_message/send_message_with_reply via send_gateway_reply helper
• gateway/src/schema.rs: Add quote_message_id field
• gateway/src/adapters/feishu.rs: handle_reply uses quote_message_id as reply target with fallback
• gateway/src/adapters/googlechat.rs + gateway/src/main.rs: Test constructions
• docs/feishu.md: Add Agent-Controlled Reply-To section
• docs/output-directives.md: Update to include Feishu support

Configuration

No new configuration. Uses existing [[reply_to:message_id]] directive from #777.

Testing

• Core: 274 tests pass
• Gateway: 126 tests pass
• Clippy: clean
• E2E: Agent outputs [[reply_to:om_xxx]] → Feishu shows native quote reply UI ✅

Backward Compatibility

• quote_message_id uses skip_serializing_if = None (core) + #[serde(default)] (gateway)
• Old core ↔ new gateway: field absent, no behavior change
• New core ↔ old gateway: unknown field ignored by serde

Discussion

https://discord.com/channels/1491295327620169908/1500160821567684660

[shaun-agent]

OpenAB PR Screening

This is auto-generated by the OpenAB project-screening flow for context collection and reviewer handoff.
Click 👍 if you find this useful. Human review will be done within 24 hours. We appreciate your support and contribution 🙏

• Title: feat(gateway): support [[reply_to]] directive for gateway platforms
• Source: feat(gateway): support [[reply_to]] directive for gateway platforms #783
• Status: moved to PR-Screening
• Generated at: 2026-05-10T06:31:23.362Z
• Discord thread: https://discord.com/channels/1488041051187974246/1502920794697629780

Screening report

## Intent

PR #783 extends OpenAB gateway delivery so an agent can intentionally send a platform-native reply or quote from its output using [[reply_to:message_id]].

The operator-visible problem is that gateway platforms currently cannot consistently preserve reply context chosen by the agent. On Feishu specifically, an agent response that should quote a prior message is sent as a normal message unless gateway delivery carries an explicit reply target.

Feat

Feature.

The PR adds a gateway protocol field, quote_message_id, and wires it through core gateway sending into the Feishu gateway adapter. When present, Feishu sends the response through its native reply API so the platform shows quote/reference UI. If the reply call fails, delivery falls back to a plain send.

It also updates docs and test constructions for the new field.

Who It Serves

Primary beneficiaries:

• Feishu users, who get native quoted replies instead of contextless bot messages
• Agent authors, who can explicitly control which message a response targets
• Gateway maintainers, who get a clearer protocol field instead of overloading existing reply semantics
• Reviewers, who need confidence that reply behavior remains backward compatible across old/new core and gateway versions

Rewritten Prompt

Implement gateway support for the existing [[reply_to:message_id]] output directive.

Add an optional quote_message_id field to the core-to-gateway reply payload and gateway schema. When send_message_with_reply(channel, text, message_id) is used by the gateway adapter, serialize message_id into quote_message_id.

Update the Feishu adapter so replies prefer quote_message_id as the native reply target and fall back to existing thread behavior only when no explicit quote target is provided. If the Feishu reply API fails, log the failure and retry as a plain message send, matching existing Discord behavior.

Preserve backward compatibility: absent quote_message_id must deserialize cleanly, and older gateways should ignore the field. Add focused tests or fixtures covering serialization/deserialization, Feishu reply target selection, and fallback behavior. Update Feishu and output directive docs to describe platform support.

Merge Pitch

This is worth advancing because it closes the gap between agent-controlled reply intent and gateway platform delivery. It keeps the directive model consistent across Discord and gateway-backed platforms while making Feishu the first concrete gateway implementation.

Risk is moderate-low if the protocol field is truly optional and fallback behavior is well tested. The main reviewer concern will be semantic overlap: reply_to, thread_id, quote_message_id, and platform-specific identifiers need clear boundaries so future adapters do not misuse the field.

Best-Practice Comparison

OpenClaw principles relevant here:

• Explicit delivery routing is directly relevant. quote_message_id makes reply targeting part of the delivery contract instead of leaving it implicit or platform-owned.
• Retry/backoff and run logs are partially relevant. This PR includes fallback-on-failure, but reviewers should check whether the failure is logged with enough context to debug bad message IDs or Feishu API failures.
• Isolated executions, durable job persistence, and gateway-owned scheduling are not central to this PR. The change is message delivery semantics, not scheduling or execution lifecycle.

Hermes Agent principles relevant here:

• Self-contained prompts for scheduled tasks are not directly relevant.
• Fresh session per scheduled run and daemon tick model are not relevant.
• File locking and atomic persisted state are not relevant unless gateway reply delivery is persisted elsewhere, which this PR does not appear to touch.
• The closest Hermes comparison is its platform-owned reply mode, but this PR intentionally moves beyond that by letting the agent choose the reply target.

Overall, this PR aligns more with OpenClaw’s explicit delivery routing than with Hermes’ scheduled-run mechanics.

Implementation Options

Conservative option: accept quote_message_id only as an optional gateway payload field and implement Feishu support exactly as proposed. Keep behavior limited to Feishu, preserve fallback to plain send, and document that other gateway adapters ignore the field for now.

Balanced option: merge the protocol field plus Feishu support, but add shared gateway tests for schema compatibility and adapter-level tests for target precedence: quote_message_id first, then existing thread behavior. Also document field semantics in a gateway protocol section so future adapters implement it consistently.

Ambitious option: formalize gateway delivery intent as a richer enum or structured target object, such as plain message, reply/quote, thread reply, edit, or platform-specific action. Migrate Feishu and other adapters toward that model over time to reduce overloaded fields and make delivery behavior auditable.

Comparison Table

Option	Speed to ship	Complexity	Reliability	Maintainability	User impact	Fit for OpenAB right now
Conservative: optional field + Feishu only	High	Low	Medium	Medium	Medium-High for Feishu	Good
Balanced: field + Feishu + protocol/tests	Medium	Medium	High	High	Medium-High	Best
Ambitious: structured delivery intent model	Low	High	High long-term	High long-term	High eventually	Too large for this PR

Recommendation

Advance the balanced option.

The PR’s core direction is sound: a dedicated optional quote_message_id is clearer than overloading existing fields, and Feishu support provides a concrete platform win. Before merge, tighten the review around protocol semantics, compatibility tests, and Feishu fallback logging.

Keep the broader delivery-intent redesign out of this PR. If reviewers agree the field naming and precedence rules are right, merge this as the first gateway implementation, then open follow-up work for additional adapters and a more formal gateway delivery contract if the pattern repeats.

[CHC-Agent]

FIXED ✅ — All findings resolved in commits c212e81 + 95f3912.

Findings

#	Severity	Finding	Status
1	🔴	Pending map memory leak — WS send failure skips cleanup (src/gateway.rs)	✅ Fixed in c212e81
2	🔴	Chunked messages silently lost when quote_message_id invalid (feishu.rs)	✅ Fixed in c212e81
3	🟡	Fallback warn log lacks quote_message_id / channel_id context	✅ Fixed in c212e81
4	🟡	reply_to vs quote_message_id doc comment 缺乏區分	✅ Fixed in 95f3912
5	🟡	Timeout catch-all silently swallows distinct failure modes	✅ Fixed in 95f3912
6	🟢	5s timeout hardcoded magic number	✅ Fixed in 95f3912

What We Changed

c212e81

• src/gateway.rs — WS send 失敗時先清 pending map entry 再 return error，防止 memory leak
• gateway/src/adapters/feishu.rs — chunked path 加 fallback（quote 失敗改用 thread_id 重試）+ warn log 加 structured fields

95f3912

• src/gateway.rs — timeout match 拆成三個 arm（failure / channel closed / timeout）各自 warn log；抽出 GATEWAY_REPLY_TIMEOUT_SECS const
• src/gateway.rs + gateway/src/schema.rs — quote_message_id doc comment 加上與 reply_to 的語義區分說明

---

Reviewer: CHC-Agent

[CHC-Agent]

All findings addressed. LGTM ✅

Two blocking issues (pending map leak + chunked message loss) and four non-blocking improvements resolved in c212e81 + 95f3912. Design is sound, backward compatibility preserved, fallback behavior consistent with Discord adapter.

Recommend merge.

[chaodu-agent]

CHANGES REQUESTED ⚠️ — Good refactor with clean protocol design, but has a redundant cleanup pattern and missing test coverage for the new fallback path.

What This PR Does

Extends the gateway protocol to support agent-controlled reply-to ([[reply_to:message_id]] directive) on gateway platforms. Feishu is the first adapter to implement this — showing native quote reference UI when an agent replies to a specific message.

How It Works

Adds quote_message_id: Option<String> to GatewayReply (both core and gateway schema). Core side: refactors send_message into a shared send_gateway_reply helper and implements send_message_with_reply for GatewayAdapter. Gateway side: Feishu handle_reply uses quote_message_id as the reply target (priority over thread_id), with automatic fallback to plain send on failure.

Findings

#	Severity	Finding	Location
1	🟡	Redundant pending.remove(id) in non-timeout branches	src/gateway.rs:207-213
2	🟡	No test for quote_message_id = Some(...) path	gateway/src/adapters/feishu.rs
3	🟢	Clean reply_to vs quote_message_id semantic separation	gateway/src/schema.rs
4	🟢	Good refactor — send_message is now a one-liner	src/gateway.rs
5	🟢	Backward-compatible serde annotations	—

Finding Details

🟡 F1: Redundant pending.remove(id) in non-timeout branches

In send_gateway_reply, the Ok(Ok(_resp)) (failure response) and Ok(Err(_)) (channel closed) branches both call self.pending.lock().await.remove(id). However, when the oneshot receiver delivers a value, the sender has already consumed the pending entry. Only the timeout branch (Err(_)) genuinely needs the remove since the sender hasn't fired yet.

This is harmless (remove on a missing key is a no-op) but misleading — it suggests the entry might still be there. Consider removing the redundant calls or adding a comment explaining they're defensive.

🟡 F2: No test for quote_message_id = Some(...) path

The PR adds quote_message_id: None to all existing test fixtures (correct for backward compat), but doesn't add a test case where quote_message_id is Some("om_xxx") to verify:

• The Feishu adapter passes it as reply_target
• The fallback logic triggers when the reply API fails

A unit test for the fallback path would increase confidence in the retry logic.

🟢 F3: Clean protocol separation

The doc comment clearly explains reply_to (routing/dedup) vs quote_message_id (visual reply UI). This avoids overloading the existing field and is self-documenting.

🟢 F4: Good refactor

Extracting send_gateway_reply eliminates ~35 lines of duplication. send_message becomes self.send_gateway_reply(channel, content, None).await — clean and readable.

🟢 F5: Backward-compatible serde

#[serde(default)] on gateway side + #[serde(skip_serializing_if)] on core side ensures old↔new interop works without breaking existing deployments.

Baseline Check

• PR opened: 2026-05-10
• Main already has: [[reply_to]] directive parsing (src/adapter.rs), send_message_with_reply trait method (default impl falls back to send_message), GatewayReply schema with reply_to field
• Net-new value: GatewayAdapter now overrides send_message_with_reply, new quote_message_id field in protocol, Feishu adapter handles it with fallback

What's Good (🟢)

• Protocol design is clean — dedicated field avoids overloading reply_to
• Refactor is well-scoped and reduces code
• Fallback behavior matches Discord adapter (silent degradation)
• Documentation updated in both feishu.md and output-directives.md
• All existing test fixtures updated for the new field