Simply Patrick Hopes can always go up, tears can only come down.

#[async_trait]
pub trait Memory: Send + Sync {
    fn name(&self) -> &str;

    async fn store(
        &self,
        key: &str,
        content: &str,
        category: MemoryCategory,
        session_id: Option<&str>,
    ) -> anyhow::Result<()>;

    async fn recall(
        &self,
        query: &str,
        limit: usize,
        session_id: Option<&str>,
    ) -> anyhow::Result<Vec<MemoryEntry>>;

    async fn get(&self, key: &str) -> anyhow::Result<Option<MemoryEntry>>;
    async fn list(
        &self,
        category: Option<&MemoryCategory>,
        session_id: Option<&str>,
    ) -> anyhow::Result<Vec<MemoryEntry>>;
    async fn forget(&self, key: &str) -> anyhow::Result<bool>;
    async fn count(&self) -> anyhow::Result<usize>;
    async fn health_check(&self) -> bool;
}

pub struct MemoryEntry {
    pub id: String,
    pub key: String,
    pub content: String,
    pub category: MemoryCategory,
    pub timestamp: String,
    pub session_id: Option<String>,
    pub score: Option<f64>,  // 只有 recall() 會填，get()/list() 都是 None
}

pub enum MemoryCategory {
    Core,             // 長期事實、偏好、決策
    Daily,            // 每日工作日誌
    Conversation,     // 對話上下文
    Custom(String),   // 開放式擴充點
}

-- 主要記憶表
CREATE TABLE memories (
    id         TEXT PRIMARY KEY,
    key        TEXT UNIQUE NOT NULL,   -- upsert 的 identity key
    content    TEXT NOT NULL,
    category   TEXT NOT NULL DEFAULT 'core',
    embedding  BLOB,                   -- f32 向量，little-endian bytes
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL,
    session_id TEXT
);

-- FTS5 全文搜尋虛擬表
CREATE VIRTUAL TABLE memories_fts USING fts5(
    key, content,
    content=memories, content_rowid=rowid
);

-- Embedding LRU 快取
CREATE TABLE embedding_cache (
    content_hash TEXT PRIMARY KEY,  -- SHA-256 前 16 hex chars
    embedding    BLOB NOT NULL,
    created_at   TEXT NOT NULL,
    accessed_at  TEXT NOT NULL      -- LRU 用
);

let result = tokio::task::spawn_blocking(move || {
    let conn = db.lock();
    conn.execute("INSERT INTO memories ...", params![...])?;
    Ok(())
}).await??;

let (tx, rx) = mpsc::channel();
thread::spawn(move || {
    let _ = tx.send(Connection::open(&path));
});
match rx.recv_timeout(Duration::from_secs(capped)) {
    Ok(Ok(conn)) => conn,
    Ok(Err(e)) => return Err(e.into()),
    Err(_) => return Err(anyhow!("SQLite open timed out")),
}

pub fn cosine_similarity(a: &[f32], b: &[f32]) -> f32 {
    let mut dot = 0.0_f64;
    let mut norm_a = 0.0_f64;
    let mut norm_b = 0.0_f64;

    for (x, y) in a.iter().zip(b.iter()) {
        let x = f64::from(*x);
        let y = f64::from(*y);
        dot += x * y;
        norm_a += x * x;
        norm_b += y * y;
    }
    let denom = norm_a.sqrt() * norm_b.sqrt();
    if !denom.is_finite() || denom < f64::EPSILON {
        return 0.0;
    }
    (dot / denom).clamp(0.0, 1.0) as f32
}

let fts_query = query
    .split_whitespace()
    .map(|w| format!("\"{w}\""))
    .collect::<Vec<_>>()
    .join(" OR ");

pub fn hybrid_merge(
    vector_results: &[(String, f32)],   // (id, cosine)
    keyword_results: &[(String, f32)],  // (id, -BM25)
    vector_weight: f32,                 // 預設 0.7
    keyword_weight: f32,                // 預設 0.3
    limit: usize,
) -> Vec<ScoredResult> {
    // BM25 分數正規化到 [0,1]
    // final_score = 0.7 * cosine + 0.3 * normalized_BM25
    // 去重：HashMap keyed on id
}

-- 保留最新的 N 筆，刪除多餘的舊資料
DELETE FROM embedding_cache WHERE content_hash IN (
    SELECT content_hash FROM embedding_cache
    ORDER BY accessed_at ASC
    LIMIT MAX(0, (SELECT COUNT(*) FROM embedding_cache) - ?1)
)

#[async_trait]
pub trait EmbeddingProvider: Send + Sync {
    fn name(&self) -> &str;
    fn dimensions(&self) -> usize;
    async fn embed(&self, texts: &[&str]) -> anyhow::Result<Vec<Vec<f32>>>;

    // 唯一的預設方法：批次 embed 的單一版本
    async fn embed_one(&self, text: &str) -> anyhow::Result<Vec<f32>> {
        let mut results = self.embed(&[text]).await?;
        results.pop().ok_or_else(|| anyhow!("Empty embedding result"))
    }
}

pub fn create_embedding_provider(provider: &str, api_key: ..., model: &str, dims: usize) {
    match provider {
        "openai" => Box::new(OpenAiEmbedding::new("https://api.openai.com", ...)),
        name if name.starts_with("custom:") => {
            let base_url = name.strip_prefix("custom:").unwrap_or("");
            Box::new(OpenAiEmbedding::new(base_url, ...))  // 指向 Ollama、本地推理伺服器等
        }
        _ => Box::new(NoopEmbedding),
    }
}

pub struct LucidMemory {
    local: SqliteMemory,
    recall_timeout: Duration,           // 預設 500ms
    store_timeout: Duration,            // 預設 800ms
    local_hit_threshold: usize,         // 預設 3：本地結果夠多就不問 Lucid
    failure_cooldown: Duration,         // 任何錯誤後冷卻 15 秒
    last_failure_at: Mutex<Option<Instant>>,
}

let signature = format!("{}\u{0}{}", entry.key.to_lowercase(), entry.content.to_lowercase());

#[async_trait]
pub trait Tool: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> serde_json::Value;
    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult>;

    // 預設實作：把前三個方法組裝成 ToolSpec，免費附贈
    fn spec(&self) -> ToolSpec {
        ToolSpec {
            name: self.name().to_string(),
            description: self.description().to_string(),
            parameters: self.parameters_schema(),
        }
    }
}

// 每次執行的回傳值
pub struct ToolResult {
    pub success: bool,
    pub output: String,
    pub error: Option<String>,
}

// 送給 LLM 描述「這個工具能做什麼」的規格書
pub struct ToolSpec {
    pub name: String,
    pub description: String,
    pub parameters: serde_json::Value,  // JSON Schema 物件
}

fn parameters_schema(&self) -> serde_json::Value {
    json!({
        "type": "object",
        "properties": {
            "command": {
                "type": "string",
                "description": "The shell command to execute"
            },
            "approved": {
                "type": "boolean",
                "description": "Set true to explicitly approve medium/high-risk commands",
                "default": false
            }
        },
        "required": ["command"]
    })
}

// 最小集合，給測試和簡單 agent 用
pub fn default_tools(security: Arc<SecurityPolicy>) -> Vec<Box<dyn Tool>> {
    vec![
        Box::new(ShellTool::new(security.clone(), runtime)),
        Box::new(FileReadTool::new(security.clone())),
        Box::new(FileWriteTool::new(security)),
    ]
}

// 完整工具集，根據設定條件啟用
pub fn all_tools_with_runtime(config, security, runtime, memory, ...) -> Vec<Box<dyn Tool>> {
    let mut tools: Vec<Box<dyn Tool>> = vec![
        Box::new(ShellTool::new(...)),
        Box::new(FileReadTool::new(...)),
        Box::new(CronAddTool::new(...)),
        Box::new(MemoryStoreTool::new(...)),
        // ...
    ];

    // 條件啟用：設定決定工具集，不是全部預設開啟
    if browser_config.enabled {
        tools.push(Box::new(BrowserTool::new_with_backend(...)));
    }
    if http_config.enabled {
        tools.push(Box::new(HttpRequestTool::new(...)));
    }
    if !agents.is_empty() {
        tools.push(Box::new(DelegateTool::new(agents, ...)));
    }
    tools
}

fn find_tool<'a>(tools: &'a [Box<dyn Tool>], name: &str) -> Option<&'a dyn Tool> {
    tools.iter().find(|t| t.name() == name).map(|t| t.as_ref())
}

fn tools_to_openai_format(tools: &[Box<dyn Tool>]) -> Vec<serde_json::Value> {
    tools.iter().map(|tool| {
        json!({
            "type": "function",
            "function": {
                "name": tool.name(),
                "description": tool.description(),
                "parameters": tool.parameters_schema()
            }
        })
    }).collect()
}

pub enum CleaningStrategy {
    Gemini,       // 最嚴格
    Anthropic,
    OpenAI,       // 最寬鬆
    Conservative, // 保守策略，適合未知 provider
}

pub struct SchemaCleanr;

impl SchemaCleanr {
    pub fn clean_for_gemini(schema: Value) -> Value { ... }
    pub fn clean_for_anthropic(schema: Value) -> Value { ... }
    pub fn clean_for_openai(schema: Value) -> Value { ... }
}

// 每個有 I/O 的工具都在建構時收到 SecurityPolicy
pub struct FileReadTool {
    security: Arc<SecurityPolicy>,
}

pub struct ShellTool {
    security: Arc<SecurityPolicy>,
    runtime: Arc<dyn RuntimeAdapter>,
}

async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult> {
    let path = args.get("path").and_then(|v| v.as_str())...;
    // 安全檢查在 execute 裡，繞不過去
    if !self.security.is_path_allowed(path) {
        return Ok(ToolResult { success: false, error: Some("Path not allowed".into()), ... });
    }
    // 繼續執行...
}

pub struct DelegateTool {
    agents: Arc<HashMap<String, DelegateAgentConfig>>,
    depth: u32,  // 防止無限委派遞迴
}

fn parameters_schema(&self) -> serde_json::Value {
    // 根據目前設定的 agent 列表動態生成 schema
    let agent_names: Vec<&str> = self.agents.keys().map(|s| s.as_str()).collect();
    json!({
        "properties": {
            "agent": {
                "type": "string",
                "description": format!("Which agent to delegate to. Available: {}",
                                       agent_names.join(", "))
            },
            "task": { "type": "string", "description": "Task description for the agent" }
        }
    })
}

async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult> {
    if self.depth >= MAX_DELEGATION_DEPTH {
        return Ok(ToolResult { success: false, error: Some("Max delegation depth reached"), ... });
    }
    let provider = create_provider(&agent_config.provider, ...)?;
    // 120 秒 timeout，防止 sub-agent 跑太久
    tokio::time::timeout(Duration::from_secs(120),
        provider.chat_with_system(...)).await
}

async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult> {
    // 清除所有環境變數，防止 API key 洩漏給子行程
    let mut cmd = Command::new("sh");
    cmd.env_clear();  // 全部清空
    for key in SAFE_ENV_VARS {  // 只加回白名單裡的
        if let Ok(val) = std::env::var(key) {
            cmd.env(key, val);
        }
    }
    // 60 秒 timeout，截斷輸出到 1MB
    tokio::time::timeout(Duration::from_secs(60), cmd.output()).await
}

#[async_trait]
pub trait Channel: Send + Sync {
    fn name(&self) -> &str;
    async fn send(&self, message: &SendMessage) -> anyhow::Result<()>;
    async fn listen(&self, tx: tokio::sync::mpsc::Sender<ChannelMessage>) -> anyhow::Result<()>;

    // 以下都有預設空實作（no-op）
    async fn health_check(&self) -> bool { true }
    async fn start_typing(&self, _recipient: &str) -> anyhow::Result<()> { Ok(()) }
    async fn stop_typing(&self, _recipient: &str) -> anyhow::Result<()> { Ok(()) }

    // 串流草稿更新（目前只有 Telegram 實作）
    fn supports_draft_updates(&self) -> bool { false }
    async fn send_draft(&self, _message: &SendMessage) -> anyhow::Result<Option<String>> { Ok(None) }
    async fn update_draft(&self, _recipient: &str, _message_id: &str, _text: &str) -> anyhow::Result<()> { Ok(()) }
    async fn finalize_draft(&self, _recipient: &str, _message_id: &str, _text: &str) -> anyhow::Result<()> { Ok(()) }
}

pub struct ChannelMessage {
    pub id: String,           // 去重用的 ID
    pub sender: String,       // 發送者識別碼
    pub reply_target: String, // 要回覆的目標（chat_id、channel_id 等）
    pub content: String,      // 正規化後的純文字內容
    pub channel: String,      // "telegram" | "discord" | "slack" | ...
    pub timestamp: u64,
}

pub struct SendMessage {
    pub content: String,
    pub recipient: String,        // 平台專屬的目標識別碼
    pub subject: Option<String>,  // Email 用的主旨
}

// 監控重啟
loop {
    let result = ch.listen(tx.clone()).await;
    // 正常退出 → 重置退避；錯誤 → 等待後重試
    tokio::time::sleep(Duration::from_secs(backoff)).await;
    backoff = backoff.saturating_mul(2).min(max_backoff);
}

// 信號量限流
let semaphore = Arc::new(Semaphore::new(max_in_flight));
while let Some(msg) = rx.recv().await {
    let permit = semaphore.acquire_owned().await?;
    workers.spawn(async move {
        let _permit = permit;  // drop 時自動釋放
        process_channel_message(worker_ctx, msg).await;
    });
}

#[async_trait]
pub trait Provider: Send + Sync {
    async fn chat_with_system(
        &self,
        system_prompt: Option<&str>,
        message: &str,
        model: &str,
        temperature: f64,
    ) -> anyhow::Result<String>;

    // 其他方法都有預設實作，最終都會呼叫 chat_with_system
    async fn simple_chat(&self, message: &str, model: &str, temperature: f64) -> anyhow::Result<String> { ... }
    async fn chat_with_history(&self, messages: &[ChatMessage], ...) -> anyhow::Result<String> { ... }
    async fn chat(&self, request: ChatRequest<'_>, ...) -> anyhow::Result<ChatResponse> { ... }
    // ...
}

pub struct ChatMessage {
    pub role: String,   // "system", "user", "assistant", "tool"
    pub content: String,
}

pub struct ChatResponse {
    pub text: Option<String>,
    pub tool_calls: Vec<ToolCall>,
}

pub struct ToolCall {
    pub id: String,
    pub name: String,
    pub arguments: String,  // JSON 字串
}

pub enum ConversationMessage {
    Chat(ChatMessage),
    AssistantToolCalls { text: Option<String>, tool_calls: Vec<ToolCall> },
    ToolResults(Vec<ToolResultMessage>),
}

pub struct ReliableProvider {
    providers: Vec<(String, Box<dyn Provider>)>,
    max_retries: u32,
    base_backoff_ms: u64,
    api_keys: Vec<String>,
    key_index: AtomicUsize,           // 用 AtomicUsize 做 round-robin
    model_fallbacks: HashMap<String, Vec<String>>,
}

// 用 "hint:" 前綴來指定路由
fn resolve(&self, model: &str) -> (usize, String) {
    if let Some(hint) = model.strip_prefix("hint:") {
        if let Some((idx, resolved_model)) = self.routes.get(hint) {
            return (*idx, resolved_model.clone());
        }
    }
    (self.default_index, model.to_string())
}

pub enum ToolsPayload {
    Gemini { function_declarations: Vec<serde_json::Value> },
    Anthropic { tools: Vec<serde_json::Value> },
    OpenAI { tools: Vec<serde_json::Value> },
    PromptGuided { instructions: String },  // 給不支援原生 tool call 的 provider 用
}

// 簡單建立單一 provider
create_provider(name, api_key)

// 加上重試 + fallback 功能
create_resilient_provider(..., reliability)

// 加上多 provider 路由
create_routed_provider(..., model_routes)

trait MyTrait {
    async fn do_something(&self) -> String; // ❌ 編譯錯誤
}

// 你寫的：
async fn do_something(&self) -> String { ... }

// 編譯器看到的：
fn do_something(&self) -> impl Future<Output = String> { ... }

impl MyTrait for StructA {
    // 回傳型別是某個只有編譯器知道名字的 Future_A
    async fn do_something(&self) -> String { ... }
}

impl MyTrait for StructB {
    // 回傳型別是另一個 Future_B，跟 Future_A 完全不同
    async fn do_something(&self) -> String { ... }
}

use async_trait::async_trait;

#[async_trait]
trait MyTrait {
    async fn do_something(&self) -> String;
}

#[async_trait]
impl MyTrait for MyStruct {
    async fn do_something(&self) -> String {
        "hello".to_string()
    }
}

trait MyTrait {
    fn do_something(&self) -> Pin<Box<dyn Future<Output = String> + Send + '_>>;
}

impl MyTrait for MyStruct {
    fn do_something(&self) -> Pin<Box<dyn Future<Output = String> + Send + '_>> {
        Box::pin(async move {
            "hello".to_string()
        })
    }
}

#[async_trait(?Send)]
trait MyTrait {
    async fn do_something(&self) -> String;
}

trait MyTrait {
    async fn do_something(&self) -> String; // ✅ Rust 1.75+ 可以！
}

fn call(obj: &dyn MyTrait) {  // ⚠️ 可能有限制
    obj.do_something();
}