feat: add btw (by the way) ephemeral side question feature

- Add btw() method to AgentSession for asking side questions without affecting conversation history
- Implement BtwResult type with question, answer, and token usage
- Add BtwAnswer event type for streaming support
- Add independent btw_system.md prompt for simplified responses
- Implement CommandAction::BtwQuery for command handling
- Add Node.js SDK bindings with full TypeScript types
- Add Python SDK bindings with PyBtwResult class
- Add comprehensive test examples and documentation
- Update API documentation (English and Chinese)
- Bump version to 1.4.1

Key features:
- Read-only history snapshot for concurrent safety
- No tool execution (LLM knowledge + context only)
- Never modifies conversation history
- Safe to call concurrently with send()/stream()
- Returns complete token usage statistics

Examples:
- crates/code/sdk/node/examples/test_btw_feature.ts
- crates/code/sdk/node/examples/test_btw_simple.ts
- crates/code/examples/BTW_TEST_GUIDE.md

Author: RoyLin

core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "a3s-code-core"
-version = "1.4.0"
+version = "1.4.1"
 edition = "2021"
 authors = ["A3S Lab Team"]
 license = "MIT"

core/prompts/btw_system.md

@@ -0,0 +1,10 @@
+You are answering a transient side question from the user.
+
+The conversation history above provides your full context.
+Your answer will NOT be saved to the conversation — it is ephemeral.
+
+Guidelines:
+- Answer concisely and directly based on the conversation context
+- Do not use any tools; answer only from what is already in context
+- If the answer cannot be determined from the context, say so clearly
+- Do not acknowledge that this is a "side question" or mention that it is ephemeral

core/src/agent.rs

@@ -493,6 +493,20 @@ pub enum AgentEvent {
         operation: String,
         error: String,
     },
+
+    // ========================================================================
+    // Side question (btw)
+    // ========================================================================
+    /// Ephemeral side question answered.
+    ///
+    /// Emitted by [`crate::agent_api::AgentSession::btw()`] in streaming mode.
+    /// The answer is never added to conversation history.
+    #[serde(rename = "btw_answer")]
+    BtwAnswer {
+        question: String,
+        answer: String,
+        usage: TokenUsage,
+    },
 }
 
 /// Result of agent execution

core/src/agent_api.rs

@@ -18,7 +18,7 @@
 
 use crate::agent::{AgentConfig, AgentEvent, AgentLoop, AgentResult};
 use crate::commands::{
-    CommandContext, CommandRegistry, CronCancelCommand, CronListCommand, LoopCommand,
+    CommandAction, CommandContext, CommandRegistry, CronCancelCommand, CronListCommand, LoopCommand,
 };
 use crate::config::CodeConfig;
 use crate::error::{read_or_recover, write_or_recover, Result};
@@ -1333,6 +1333,24 @@ impl Agent {
     }
 }
 
+// ============================================================================
+// BtwResult
+// ============================================================================
+
+/// Result of a `/btw` ephemeral side question.
+///
+/// The answer is never added to conversation history.
+/// Returned by [`AgentSession::btw()`].
+#[derive(Debug, Clone)]
+pub struct BtwResult {
+    /// The original question.
+    pub question: String,
+    /// The LLM's answer.
+    pub answer: String,
+    /// Token usage for this ephemeral call.
+    pub usage: crate::llm::TokenUsage,
+}
+
 // ============================================================================
 // AgentSession
 // ============================================================================
@@ -1509,7 +1527,21 @@ impl AgentSession {
         // Slash command interception
         if CommandRegistry::is_command(prompt) {
             let ctx = self.build_command_context();
-            if let Some(output) = self.command_registry().dispatch(prompt, &ctx) {
+            let output = self.command_registry().dispatch(prompt, &ctx);
+            // Drop the MutexGuard before any async operations
+            if let Some(output) = output {
+                // BtwQuery requires an async LLM call — handle it here.
+                if let Some(CommandAction::BtwQuery(ref question)) = output.action {
+                    let result = self.btw(question).await?;
+                    return Ok(AgentResult {
+                        text: result.answer,
+                        messages: history
+                            .map(|h| h.to_vec())
+                            .unwrap_or_else(|| read_or_recover(&self.history).clone()),
+                        tool_calls_count: 0,
+                        usage: result.usage,
+                    });
+                }
                 return Ok(AgentResult {
                     text: output.text,
                     messages: history
@@ -1590,6 +1622,53 @@ impl AgentSession {
         Ok(result)
     }
 
+    /// Ask an ephemeral side question without affecting conversation history.
+    ///
+    /// Takes a read-only snapshot of the current history, makes a separate LLM
+    /// call with no tools, and returns the answer. History is never modified.
+    ///
+    /// Safe to call concurrently with an ongoing [`send()`](Self::send) — the
+    /// snapshot only acquires a read lock on the internal history.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    /// # async fn run(session: &a3s_code_core::AgentSession) -> anyhow::Result<()> {
+    /// let result = session.btw("what file was that error in?").await?;
+    /// println!("{}", result.answer);
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub async fn btw(&self, question: &str) -> Result<BtwResult> {
+        let question = question.trim();
+        if question.is_empty() {
+            return Err(crate::error::CodeError::Session(
+                "btw: question cannot be empty".to_string(),
+            ));
+        }
+
+        // Snapshot current history — read-only, does not block send().
+        let history_snapshot = read_or_recover(&self.history).clone();
+
+        // Append the side question as a temporary user turn.
+        let mut messages = history_snapshot;
+        messages.push(Message::user(question));
+
+        let response = self
+            .llm_client
+            .complete(&messages, Some(crate::prompts::BTW_SYSTEM), &[])
+            .await
+            .map_err(|e| {
+                crate::error::CodeError::Llm(format!("btw: ephemeral LLM call failed: {e}"))
+            })?;
+
+        Ok(BtwResult {
+            question: question.to_string(),
+            answer: response.text(),
+            usage: response.usage,
+        })
+    }
+
     /// Send a prompt with image attachments and wait for the complete response.
     ///
     /// Images are included as multi-modal content blocks in the user message.
@@ -1673,8 +1752,51 @@ impl AgentSession {
         // Slash command interception for streaming
         if CommandRegistry::is_command(prompt) {
             let ctx = self.build_command_context();
-            if let Some(output) = self.command_registry().dispatch(prompt, &ctx) {
+            let output = self.command_registry().dispatch(prompt, &ctx);
+            // Drop the MutexGuard before spawning async tasks
+            if let Some(output) = output {
                 let (tx, rx) = mpsc::channel(256);
+
+                // BtwQuery: make the ephemeral call and emit BtwAnswer event.
+                if let Some(CommandAction::BtwQuery(question)) = output.action {
+                    // Snapshot history and clone the client before entering the task.
+                    let llm_client = self.llm_client.clone();
+                    let history_snapshot = read_or_recover(&self.history).clone();
+                    let handle = tokio::spawn(async move {
+                        let mut messages = history_snapshot;
+                        messages.push(Message::user(&question));
+                        match llm_client
+                            .complete(&messages, Some(crate::prompts::BTW_SYSTEM), &[])
+                            .await
+                        {
+                            Ok(response) => {
+                                let answer = response.text();
+                                let _ = tx
+                                    .send(AgentEvent::BtwAnswer {
+                                        question: question.clone(),
+                                        answer: answer.clone(),
+                                        usage: response.usage,
+                                    })
+                                    .await;
+                                let _ = tx
+                                    .send(AgentEvent::End {
+                                        text: answer,
+                                        usage: crate::llm::TokenUsage::default(),
+                                    })
+                                    .await;
+                            }
+                            Err(e) => {
+                                let _ = tx
+                                    .send(AgentEvent::Error {
+                                        message: format!("btw failed: {e}"),
+                                    })
+                                    .await;
+                            }
+                        }
+                    });
+                    return Ok((rx, handle));
+                }
+
                 let handle = tokio::spawn(async move {
                     let _ = tx
                         .send(AgentEvent::TextDelta {

core/src/commands.rs

@@ -81,6 +81,11 @@ pub enum CommandAction {
     ClearHistory,
     /// Switch to a different model.
     SwitchModel(String),
+    /// Ask an ephemeral side question (handled async by the session).
+    ///
+    /// The session makes a separate LLM call with the current history snapshot
+    /// and returns the answer without modifying conversation history.
+    BtwQuery(String),
 }
 
 impl CommandOutput {
@@ -134,6 +139,7 @@ impl CommandRegistry {
             commands: HashMap::new(),
         };
         registry.register(Arc::new(HelpCommand));
+        registry.register(Arc::new(BtwCommand));
         registry.register(Arc::new(CompactCommand));
         registry.register(Arc::new(CostCommand));
         registry.register(Arc::new(ModelCommand));
@@ -227,6 +233,30 @@ impl Default for CommandRegistry {
 
 // ─── Built-in Commands ──────────────────────────────────────────────
 
+struct BtwCommand;
+
+impl SlashCommand for BtwCommand {
+    fn name(&self) -> &str {
+        "btw"
+    }
+    fn description(&self) -> &str {
+        "Ask a side question without affecting conversation history"
+    }
+    fn usage(&self) -> Option<&str> {
+        Some("/btw <question>")
+    }
+    fn execute(&self, args: &str, _ctx: &CommandContext) -> CommandOutput {
+        let question = args.trim();
+        if question.is_empty() {
+            return CommandOutput::text(
+                "Usage: /btw <question>\nExample: /btw what file was that error in?",
+            );
+        }
+        // The actual LLM call is async — signal the session to handle it.
+        CommandOutput::with_action(String::new(), CommandAction::BtwQuery(question.to_string()))
+    }
+}
+
 struct HelpCommand;
 
 impl SlashCommand for HelpCommand {

core/src/lib.rs

@@ -91,7 +91,7 @@ pub mod tools;
 // Re-export key types at crate root for ergonomic usage
 pub use a3s_lane::MetricsSnapshot;
 pub use agent::{AgentConfig, AgentEvent, AgentLoop, AgentResult};
-pub use agent_api::{Agent, AgentSession, SessionOptions, ToolCallResult};
+pub use agent_api::{Agent, AgentSession, BtwResult, SessionOptions, ToolCallResult};
 pub use agent_teams::{
     AgentExecutor, AgentTeam, TeamConfig, TeamMember, TeamMemberOptions, TeamMessage, TeamRole,
     TeamRunResult, TeamRunner, TeamTaskBoard,

core/src/prompts.rs

@@ -105,6 +105,16 @@ pub const TEAM_REVIEWER: &str = include_str!("../prompts/team_reviewer.md");
 /// Skill catalog header injected before listing available skill names/descriptions.
 pub const SKILLS_CATALOG_HEADER: &str = include_str!("../prompts/skills_catalog_header.md");
 
+// ============================================================================
+// Side Question (btw)
+// ============================================================================
+
+/// System prompt for `/btw` ephemeral side questions.
+///
+/// Used by [`crate::agent_api::AgentSession::btw()`] — the answer is never
+/// added to conversation history.
+pub const BTW_SYSTEM: &str = include_str!("../prompts/btw_system.md");
+
 // ============================================================================
 // System Prompt Slots
 // ============================================================================
@@ -263,6 +273,7 @@ mod tests {
         assert!(!TEAM_LEAD.is_empty());
         assert!(!TEAM_REVIEWER.is_empty());
         assert!(!SKILLS_CATALOG_HEADER.is_empty());
+        assert!(!BTW_SYSTEM.is_empty());
         assert!(!PLAN_EXECUTE_GOAL.is_empty());
         assert!(!PLAN_EXECUTE_STEP.is_empty());
         assert!(!PLAN_FALLBACK_STEP.is_empty());