feat: add message_react tool for AI-chosen emoji reactions

- Add `message_react` tool so agents can choose their own reaction emoji
  instead of hardcoded lifecycle emojis
- Add `send_channel_reaction()` to KernelHandle trait and implement in kernel
- Inject [channel_context] header into messages so agents know channel,
  recipient, and message_id for the react tool
- Remove hardcoded "done" reaction — agent chooses via tool call
- Keep hardcoded "error" reaction (agent can't react on failure)
- Update bridge integration tests for channel_context header in messages

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: houko

crates/openfang-channels/src/bridge.rs

@@ -656,8 +656,14 @@ async fn dispatch_message(
     // Send typing indicator (best-effort)
     let _ = adapter.send_typing(&message.sender).await;
 
-    // Lifecycle reactions: 👀 queued → 🤔 thinking → 👍 done / 👎 error
+    // Inject channel context so agent can use message_react tool
     let msg_id = &message.platform_message_id;
+    let text_with_ctx = format!(
+        "[channel_context: channel={} recipient={} message_id={}]\n{}",
+        ct_str, &message.sender.platform_id, msg_id, &text
+    );
+
+    // Ack reaction: 👀 immediately so user knows we received it
     let _ = adapter
         .send_reaction(
             &message.sender,
@@ -671,9 +677,8 @@ async fn dispatch_message(
         .await;
 
     // Send to agent; switch to "thinking" after a short delay while waiting
-    let agent_future = handle.send_message(agent_id, &text);
+    let agent_future = handle.send_message(agent_id, &text_with_ctx);
     let thinking_delay = tokio::time::sleep(std::time::Duration::from_secs(2));
-    let mut sent_thinking = false;
 
     tokio::pin!(agent_future);
     tokio::pin!(thinking_delay);
@@ -695,25 +700,15 @@ async fn dispatch_message(
                     },
                 )
                 .await;
-            sent_thinking = true;
             // Now await the actual response
             agent_future.await
         }
     };
 
     match result {
         Ok(response) => {
-            let _ = adapter
-                .send_reaction(
-                    &message.sender,
-                    msg_id,
-                    &LifecycleReaction {
-                        phase: AgentPhase::Done,
-                        emoji: default_phase_emoji(&AgentPhase::Done).to_string(),
-                        remove_previous: true,
-                    },
-                )
-                .await;
+            // No hardcoded "done" reaction — agent can choose via message_react tool.
+            // Only clear thinking reaction if agent didn't react.
             send_response(adapter, &message.sender, response, thread_id, output_format).await;
             handle
                 .record_delivery(agent_id, ct_str, &message.sender.platform_id, true, None)
@@ -752,7 +747,6 @@ async fn dispatch_message(
                 .await;
         }
     }
-    let _ = sent_thinking; // suppress unused warning
 }
 
 /// Handle a bot command (returns the response text).

crates/openfang-channels/tests/bridge_integration_test.rs

@@ -225,18 +225,31 @@ async fn test_bridge_dispatch_text_message() {
     // Give the async dispatch loop time to process
     tokio::time::sleep(tokio::time::Duration::from_millis(100)).await;
 
-    // Verify: adapter received the echo response
+    // Verify: adapter received the echo response (now includes channel_context prefix)
     let sent = adapter_ref.get_sent();
     assert_eq!(sent.len(), 1, "Expected 1 response, got {}", sent.len());
     assert_eq!(sent[0].0, "user1");
-    assert_eq!(sent[0].1, "Echo: Hello agent!");
+    assert!(
+        sent[0].1.contains("Hello agent!"),
+        "Response should contain original message, got: {}",
+        sent[0].1
+    );
 
-    // Verify: handle received the message
+    // Verify: handle received the message with channel_context header
     {
         let received = handle.received.lock().unwrap();
         assert_eq!(received.len(), 1);
         assert_eq!(received[0].0, agent_id);
-        assert_eq!(received[0].1, "Hello agent!");
+        assert!(
+            received[0].1.contains("Hello agent!"),
+            "Handle should receive original message, got: {}",
+            received[0].1
+        );
+        assert!(
+            received[0].1.contains("[channel_context:"),
+            "Handle should receive channel_context header, got: {}",
+            received[0].1
+        );
     }
 
     manager.stop().await;
@@ -486,7 +499,10 @@ async fn test_bridge_manager_lifecycle() {
     assert_eq!(sent.len(), 5, "Expected 5 responses, got {}", sent.len());
 
     for (i, (_, text)) in sent.iter().enumerate() {
-        assert_eq!(*text, format!("Echo: message {i}"));
+        assert!(
+            text.contains(&format!("message {i}")),
+            "Response {i} should contain 'message {i}', got: {text}"
+        );
     }
 
     // Stop — should complete without hanging
@@ -535,11 +551,19 @@ async fn test_bridge_multiple_adapters() {
 
     let tg_sent = tg_ref.get_sent();
     assert_eq!(tg_sent.len(), 1);
-    assert_eq!(tg_sent[0].1, "Echo: from telegram");
+    assert!(
+        tg_sent[0].1.contains("from telegram"),
+        "Telegram response should contain original message, got: {}",
+        tg_sent[0].1
+    );
 
     let dc_sent = dc_ref.get_sent();
     assert_eq!(dc_sent.len(), 1);
-    assert_eq!(dc_sent[0].1, "Echo: from discord");
+    assert!(
+        dc_sent[0].1.contains("from discord"),
+        "Discord response should contain original message, got: {}",
+        dc_sent[0].1
+    );
 
     manager.stop().await;
 }

crates/openfang-kernel/src/kernel.rs

@@ -5397,6 +5397,41 @@ impl KernelHandle for OpenFangKernel {
         Ok(format!("{} sent to {} via {}", media_type, recipient, channel))
     }
 
+    async fn send_channel_reaction(
+        &self,
+        channel: &str,
+        recipient: &str,
+        message_id: &str,
+        emoji: &str,
+    ) -> Result<String, String> {
+        let adapter = self
+            .channel_adapters
+            .get(channel)
+            .ok_or_else(|| {
+                format!("Channel '{}' not found for reaction", channel)
+            })?
+            .clone();
+
+        let user = openfang_channels::types::ChannelUser {
+            platform_id: recipient.to_string(),
+            display_name: recipient.to_string(),
+            openfang_user: None,
+        };
+
+        let reaction = openfang_channels::types::LifecycleReaction {
+            phase: openfang_channels::types::AgentPhase::Done,
+            emoji: emoji.to_string(),
+            remove_previous: true,
+        };
+
+        adapter
+            .send_reaction(&user, message_id, &reaction)
+            .await
+            .map_err(|e| format!("Reaction failed: {e}"))?;
+
+        Ok(format!("Reacted with {} on {} via {}", emoji, message_id, channel))
+    }
+
     async fn spawn_agent_checked(
         &self,
         manifest_toml: &str,

crates/openfang-runtime/src/kernel_handle.rs

@@ -209,6 +209,20 @@ pub trait KernelHandle: Send + Sync {
         Err("Channel media send not available".to_string())
     }
 
+    /// Send an emoji reaction to a message on a channel.
+    /// `channel` is the adapter name (e.g. "telegram"), `recipient` is the user/chat ID,
+    /// `message_id` is the platform message ID, `emoji` is the emoji character.
+    async fn send_channel_reaction(
+        &self,
+        channel: &str,
+        recipient: &str,
+        message_id: &str,
+        emoji: &str,
+    ) -> Result<String, String> {
+        let _ = (channel, recipient, message_id, emoji);
+        Err("Channel reactions not available".to_string())
+    }
+
     /// Spawn an agent with capability inheritance enforcement.
     /// `parent_caps` are the parent's granted capabilities. The kernel MUST verify
     /// that every capability in the child manifest is covered by `parent_caps`.

crates/openfang-runtime/src/tool_runner.rs

@@ -306,6 +306,8 @@ pub async fn execute_tool(
 
         // Channel send tool (proactive outbound messaging)
         "channel_send" => tool_channel_send(input, kernel).await,
+        // Channel reaction tool (emoji reaction on incoming message)
+        "message_react" => tool_message_react(input, kernel).await,
 
         // Persistent process tools
         "process_start" => tool_process_start(input, process_manager, caller_agent_id).await,
@@ -1014,6 +1016,21 @@ pub fn builtin_tool_definitions() -> Vec<ToolDefinition> {
                 "required": ["channel", "recipient"]
             }),
         },
+        // --- Channel reaction tool ---
+        ToolDefinition {
+            name: "message_react".to_string(),
+            description: "Add an emoji reaction to the incoming message on the current channel (Telegram, Discord, etc). Use this to react to user messages with a contextually appropriate emoji. The channel, recipient, and message_id are provided in the [channel_context] header of the incoming message.".to_string(),
+            input_schema: serde_json::json!({
+                "type": "object",
+                "properties": {
+                    "channel": { "type": "string", "description": "Channel name (e.g. 'telegram')" },
+                    "recipient": { "type": "string", "description": "User/chat ID on the platform" },
+                    "message_id": { "type": "string", "description": "Platform message ID to react to" },
+                    "emoji": { "type": "string", "description": "Single emoji to react with (e.g. '❤️', '🎉', '👀'). For Telegram, must be from the supported set." }
+                },
+                "required": ["channel", "recipient", "message_id", "emoji"]
+            }),
+        },
         // --- Hand tools (curated autonomous capability packages) ---
         ToolDefinition {
             name: "hand_list".to_string(),
@@ -2190,6 +2207,42 @@ async fn tool_channel_send(
         .await
 }
 
+// ---------------------------------------------------------------------------
+// Channel reaction tool
+// ---------------------------------------------------------------------------
+
+async fn tool_message_react(
+    input: &serde_json::Value,
+    kernel: Option<&Arc<dyn KernelHandle>>,
+) -> Result<String, String> {
+    let kh = require_kernel(kernel)?;
+
+    let channel = input["channel"]
+        .as_str()
+        .ok_or("Missing 'channel' parameter")?
+        .trim()
+        .to_lowercase();
+    let recipient = input["recipient"]
+        .as_str()
+        .ok_or("Missing 'recipient' parameter")?
+        .trim();
+    let message_id = input["message_id"]
+        .as_str()
+        .ok_or("Missing 'message_id' parameter")?
+        .trim();
+    let emoji = input["emoji"]
+        .as_str()
+        .ok_or("Missing 'emoji' parameter")?
+        .trim();
+
+    if emoji.is_empty() {
+        return Err("Emoji cannot be empty".to_string());
+    }
+
+    kh.send_channel_reaction(&channel, recipient, message_id, emoji)
+        .await
+}
+
 // ---------------------------------------------------------------------------
 // Hand tools (delegated to kernel via KernelHandle trait)
 // ---------------------------------------------------------------------------
@@ -3121,8 +3174,8 @@ mod tests {
     fn test_builtin_tool_definitions() {
         let tools = builtin_tool_definitions();
         assert!(
-            tools.len() >= 39,
-            "Expected at least 39 tools, got {}",
+            tools.len() >= 40,
+            "Expected at least 40 tools, got {}",
             tools.len()
         );
         let names: Vec<&str> = tools.iter().map(|t| t.name.as_str()).collect();
@@ -3168,8 +3221,9 @@ mod tests {
         assert!(names.contains(&"cron_create"));
         assert!(names.contains(&"cron_list"));
         assert!(names.contains(&"cron_cancel"));
-        // 1 channel send tool
+        // channel tools
         assert!(names.contains(&"channel_send"));
+        assert!(names.contains(&"message_react"));
         // 4 hand tools
         assert!(names.contains(&"hand_list"));
         assert!(names.contains(&"hand_activate"));