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

pub trait ComicReader: Send + Sync + std::fmt::Debug {
    fn title(&self) -> &str;
    fn page_count(&self) -> usize;
    fn extract_page(&self, index: usize) -> Result<iced::widget::image::Handle, String>;
}

pub fn open(path: &Path) -> Result<Box<dyn ComicReader>, String> {
    match path
        .extension()
        .and_then(|e| e.to_str())
        .map(str::to_lowercase)
        .as_deref()
    {
        Some("cbz") => cbz::CbzReader::open(path).map(|r| Box::new(r) as Box<dyn ComicReader>),
        Some("cbr") => cbr::CbrReader::open(path).map(|r| Box::new(r) as Box<dyn ComicReader>),
        Some("cb7") => cb7::Cb7Reader::open(path).map(|r| Box::new(r) as Box<dyn ComicReader>),
        ext => Err(format!("Unsupported format: {}", ext.unwrap_or("none"))),
    }
}

Task::perform(
    async move { smol::unblock(move || reader::open(&path).map(Arc::from)).await },
    Message::ComicLoaded,
)

#[derive(Debug)]
pub struct CbzReader {
    title: String,
    pages: Vec<String>,      // 排序後的圖片檔名列表
    archive_bytes: Vec<u8>,  // 整份 .cbz 的原始位元組
}

impl ComicReader for CbzReader {
    fn extract_page(&self, index: usize) -> Result<image::Handle, String> {
        let filename = self.pages.get(index)
            .ok_or_else(|| format!("Page index {index} out of bounds"))?;
        let cursor = std::io::Cursor::new(&self.archive_bytes);
        let mut archive = zip::ZipArchive::new(cursor).map_err(|e| e.to_string())?;
        let mut file = archive.by_name(filename).map_err(|e| e.to_string())?;
        let mut bytes = Vec::new();
        file.read_to_end(&mut bytes).map_err(|e| e.to_string())?;
        Ok(image::Handle::from_bytes(bytes))
    }
}

#[derive(Debug)]
pub struct Cb7Reader {
    title: String,
    pages: Vec<Vec<u8>>,  // 每頁的原始圖片位元組，開檔時全部解壓好
}

impl Cb7Reader {
    pub fn open(path: &Path) -> Result<Self, String> {
        let mut reader = SevenZReader::open(path, Password::empty())
            .map_err(|e| e.to_string())?;

        let mut entries: Vec<(String, Vec<u8>)> = Vec::new();
        reader.for_each_entries(|entry, reader| {
            if entry.is_directory() || !super::is_image_file(entry.name()) {
                return Ok(true); // 跳過，繼續
            }
            let mut bytes = Vec::new();
            reader.read_to_end(&mut bytes).map_err(sevenz_rust::Error::from)?;
            entries.push((entry.name().to_owned(), bytes));
            Ok(true)
        }).map_err(|e| e.to_string())?;

        entries.sort_by(|(a, _), (b, _)| a.cmp(b));
        // ...
    }
}

impl CbrReader {
    pub fn open(_path: &Path) -> Result<Self, String> {
        Err(
            "CBR (RAR) format is not yet supported. \
             Consider converting to CBZ using Calibre or 7-Zip."
                .to_string(),
        )
    }
}

const CACHE_CAPACITY: usize = 7;

struct PageCache {
    entries: HashMap<usize, image::Handle>,
}

impl PageCache {
    fn insert(&mut self, index: usize, handle: image::Handle, current_page: usize) {
        if !self.entries.contains_key(&index) && self.entries.len() >= CACHE_CAPACITY {
            // 找距離 current_page 最遠的 key
            let evict = *self
                .entries
                .keys()
                .max_by_key(|&&k| k.abs_diff(current_page))
                .expect("cache is non-empty");
            self.entries.remove(&evict);
        }
        self.entries.insert(index, handle);
    }
}

// usize is Copy，所以可以在可變借用前先把 key 複製出來
let evict = *self
    .entries
    .keys()
    .max_by_key(|&&k| k.abs_diff(current_page))
    .expect("cache is non-empty");
self.entries.remove(&evict);  // 這裡才開始可變借用

#[derive(Debug, Clone)]
enum Message {
    OpenFile,
    FileSelected(Option<PathBuf>),
    ComicLoaded(Result<Arc<dyn reader::ComicReader>, String>),
    NextPage,
    PrevPage,
    PagePreloaded(usize, Option<image::Handle>),
}

// 第一步：呼叫原生對話框
Message::OpenFile => {
    Task::perform(
        async {
            rfd::AsyncFileDialog::new()
                .add_filter("Comic Book Archive", &["cbz", "cbr", "cb7"])
                .pick_file()
                .await
                .map(|f| f.path().to_owned())
        },
        Message::FileSelected,  // 完成後產生 FileSelected(Option<PathBuf>)
    )
}
// 第二步：在執行緒池解壓縮並建立 Reader
Message::FileSelected(Some(path)) => Task::perform(
    async move { smol::unblock(move || reader::open(&path).map(Arc::from)).await },
    Message::ComicLoaded,  // 完成後產生 ComicLoaded(Result<Arc<...>, String>)
),

// 背景預載的單頁提取
let comic = Arc::clone(comic);
Task::perform(
    async move {
        let handle = smol::unblock(move || comic.extract_page(idx).ok()).await;
        (idx, handle)
    },
    |(idx, handle)| Message::PagePreloaded(idx, handle),
)

fn preload_adjacent(&self, around: usize) -> Task<Message> {
    let Some(comic) = &self.comic else { return Task::none(); };
    let page_count = comic.page_count();

    let start = around.saturating_sub(PRELOAD_LOOKAHEAD);  // 避免 usize 下溢
    let end = (around + PRELOAD_LOOKAHEAD).min(page_count - 1);

    let candidates: Vec<usize> = (start..=end)
        .filter(|&i| i != around && !self.page_cache.contains(i))
        .collect();

    if candidates.is_empty() {
        return Task::none();
    }

    let tasks: Vec<Task<Message>> = candidates
        .into_iter()
        .map(|idx| {
            let comic = Arc::clone(comic);
            Task::perform(
                async move {
                    let handle = smol::unblock(move || comic.extract_page(idx).ok()).await;
                    (idx, handle)
                },
                |(idx, handle)| Message::PagePreloaded(idx, handle),
            )
        })
        .collect();

    Task::batch(tasks)  // 並行啟動所有預載任務
}

let can_prev = self.current_page > 0;
let can_next = self
    .comic
    .as_ref()
    .is_some_and(|c| self.current_page + 1 < c.page_count());

let prev_btn = button(text("◄ Previous").size(14))
    .on_press_maybe((has_comic && can_prev).then_some(Message::PrevPage));

let next_btn = button(text("Next ►").size(14))
    .on_press_maybe((has_comic && can_next).then_some(Message::NextPage));

fn nav_button_style(_theme: &Theme, status: button::Status) -> button::Style {
    let bg = match status {
        button::Status::Hovered | button::Status::Pressed => iced::color!(0x565f89),
        button::Status::Disabled => iced::color!(0x292e42),  // 暗色，表示禁用
        _ => iced::color!(0x414868),
    };
    let text_color = match status {
        button::Status::Disabled => iced::color!(0x3d4168),  // 文字也變暗
        _ => iced::color!(0xc0caf5),
    };
    // ...
}

fn subscription(&self) -> Subscription<Message> {
    iced::keyboard::on_key_press(|key, _modifiers| match key.as_ref() {
        iced::keyboard::Key::Named(Named::ArrowRight)
        | iced::keyboard::Key::Named(Named::PageDown) => Some(Message::NextPage),
        iced::keyboard::Key::Named(Named::ArrowLeft)
        | iced::keyboard::Key::Named(Named::PageUp) => Some(Message::PrevPage),
        _ => None,
    })
}

pub trait Observer: Send + Sync + 'static {
    fn record_event(&self, event: &ObserverEvent);
    fn record_metric(&self, metric: &ObserverMetric);
    fn flush(&self) {}
    fn name(&self) -> &str;
    fn as_any(&self) -> &dyn std::any::Any;
}

pub enum ObserverEvent {
    AgentStart { provider: String, model: String },
    LlmRequest { provider: String, model: String, messages_count: usize },
    LlmResponse {
        provider: String,
        model: String,
        duration: Duration,
        success: bool,
        error_message: Option<String>,
    },
    AgentEnd {
        provider: String,
        model: String,
        duration: Duration,
        tokens_used: Option<u64>,
        cost_usd: Option<f64>,
    },
    ToolCallStart { tool: String },
    ToolCall { tool: String, duration: Duration, success: bool },
    TurnComplete,
    ChannelMessage { channel: String, direction: String },
    HeartbeatTick,
    Error { component: String, message: String },
}

pub enum ObserverMetric {
    RequestLatency(Duration),
    TokensUsed(u64),
    ActiveSessions(u64),
    QueueDepth(u64),
}

pub struct NoopObserver;

impl Observer for NoopObserver {
    #[inline(always)]
    fn record_event(&self, _event: &ObserverEvent) {}

    #[inline(always)]
    fn record_metric(&self, _metric: &ObserverMetric) {}

    fn name(&self) -> &str { "noop" }
    fn as_any(&self) -> &dyn Any { self }
}

impl Observer for LogObserver {
    fn record_event(&self, event: &ObserverEvent) {
        match event {
            ObserverEvent::AgentStart { provider, model } => {
                info!(provider = %provider, model = %model, "agent.start");
            }
            ObserverEvent::LlmResponse { duration, success, .. } => {
                info!(duration_ms = duration.as_millis(), success, "llm.response");
            }
            // ...
        }
    }
}

impl Observer for VerboseObserver {
    fn record_event(&self, event: &ObserverEvent) {
        match event {
            ObserverEvent::LlmRequest { provider, model, messages_count } => {
                eprintln!("> Thinking");
                eprintln!("> Send (provider={}, model={}, messages={})",
                    provider, model, messages_count);
            }
            ObserverEvent::LlmResponse { duration, success, .. } => {
                eprintln!("< Receive (success={}, duration_ms={})",
                    success, duration.as_millis());
            }
            // ...
        }
    }
}

pub struct PrometheusObserver {
    registry: Registry,
    agent_starts: IntCounterVec,
    agent_duration: HistogramVec,
    llm_calls: IntCounterVec,
    llm_duration: Histogram,
    tool_calls: IntCounterVec,
    // ...
}

// 在 gateway 需要回應 /metrics 請求時
state.observer
    .as_any()
    .downcast_ref::<PrometheusObserver>()
    .map(|prom| prom.encode())

pub struct OtelObserver {
    tracer_provider: SdkTracerProvider,
    meter_provider: SdkMeterProvider,
    agent_starts: Counter<u64>,
    agent_duration: Histogram<f64>,
    llm_calls: Counter<u64>,
    llm_duration: Histogram<f64>,
    // ...
}

// 收到 LlmResponse 事件後，用 duration 計算出 span 的開始時間
let start_time = SystemTime::now() - duration;
let mut span = tracer.build(
    SpanBuilder::from_name("llm.call")
        .with_start_time(start_time)
        .with_attributes(vec![
            KeyValue::new("provider", provider.clone()),
            KeyValue::new("model", model.clone()),
            KeyValue::new("success", *success),
        ])
);
span.set_status(if *success { Status::Ok } else { Status::error("") });
span.end();

pub struct MultiObserver {
    observers: Vec<Box<dyn Observer>>,
}

impl Observer for MultiObserver {
    fn record_event(&self, event: &ObserverEvent) {
        for obs in &self.observers {
            obs.record_event(event);
        }
    }
}

pub fn create_observer(config: &ObservabilityConfig) -> Box<dyn Observer> {
    match config.backend.as_str() {
        "log" => Box::new(LogObserver::new()),
        "prometheus" => Box::new(PrometheusObserver::new()),
        "otel" | "opentelemetry" | "otlp" => {
            match OtelObserver::new(config.otel_endpoint.as_deref(), ...) {
                Ok(obs) => Box::new(obs),
                Err(e) => {
                    tracing::error!("Failed to create OTel observer: {e}. Falling back to noop.");
                    Box::new(NoopObserver)
                }
            }
        }
        _ => Box::new(NoopObserver),
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ObservabilityConfig {
    pub backend: String,          // "none" | "log" | "prometheus" | "otel"
    pub otel_endpoint: Option<String>,      // 預設 http://localhost:4318
    pub otel_service_name: Option<String>,  // 預設 "zeroclaw"
}

impl Default for ObservabilityConfig {
    fn default() -> Self {
        Self { backend: "none".into(), .. }
    }
}

pub struct Agent {
    observer: Arc<dyn Observer>,
    // ...
}

self.observer.record_event(&ObserverEvent::AgentStart {
    provider: provider_name.clone(),
    model: self.model_name.clone(),
});

// ... 執行 LLM 呼叫 ...

self.observer.record_event(&ObserverEvent::LlmResponse {
    provider: provider_name.clone(),
    model: self.model_name.clone(),
    duration,
    success: true,
    error_message: None,
});

fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Output>

struct MyFuture {
    inner: SomeFuture,
}

impl Future for MyFuture {
    type Output = i32;

    fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll<i32> {
        // inner 也需要 Pin<&mut SomeFuture> 才能被 poll
        // 但 self 是 Pin<&mut MyFuture>，
        // 不能直接取出 &mut self.inner，因為那樣可能讓 inner 被 move
        self.inner.poll(cx) // ❌ SomeFuture::poll 需要 Pin<&mut Self>，不是 &mut Self
    }
}

fn takes_mut(r: &mut i32) { *r += 1; }

let mut x = 0;
let r = &mut x;

takes_mut(r);  // Rust 自動 reborrow，等同於 takes_mut(&mut *r)
takes_mut(r);  // ✅ r 沒有被消費，可以繼續使用

fn poll_it<F: Future>(p: Pin<&mut F>, cx: &mut Context<'_>) -> Poll<F::Output> {
    p.poll(cx)
}

let mut fut = some_async_fn();
// 用 unsafe 建立 Pin<&mut _> 做示範
let mut pinned = unsafe { Pin::new_unchecked(&mut fut) };

poll_it(pinned, cx);  // pinned 被 move 進去，消費掉了
poll_it(pinned, cx);  // ❌ 編譯錯誤：use of moved value: `pinned`

impl<P: DerefMut> Pin<P> {
    pub fn as_mut(&mut self) -> Pin<&mut P::Target>
}

fn poll(mut self: Pin<&mut Self>, cx: &mut Context) -> Poll<i32> {
    // as_mut() 借出一個新的 Pin<&mut MyFuture>
    // 原本的 self 還活著，可以繼續使用
    let _pin1 = self.as_mut(); // Pin<&mut MyFuture>
    let _pin2 = self.as_mut(); // 還可以再借
}

fn poll(mut self: Pin<&mut Self>, cx: &mut Context) -> Poll<i32> {
    // as_mut() 先做 reborrow
    // map_unchecked_mut() 再投影到 inner 欄位
    let inner_pin: Pin<&mut SomeFuture> = unsafe {
        self.as_mut().map_unchecked_mut(|s| &mut s.inner)
    };
    inner_pin.poll(cx)
}

use pin_project::pin_project;
use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};

#[pin_project]
struct Timeout<F: Future> {
    #[pin]          // ← 標記這個欄位需要被 pin
    inner: F,
    deadline: std::time::Instant,
}

impl<F: Future> Future for Timeout<F> {
    type Output = Option<F::Output>;

    fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Self::Output> {
        let this = self.project(); // 安全地做 projection，無需 unsafe

        // this.inner 的型別是 Pin<&mut F>   ← 已經 pin 好，可以直接 poll
        // this.deadline 的型別是 &mut Instant ← 普通可變引用
        if std::time::Instant::now() >= *this.deadline {
            return Poll::Ready(None);
        }

        match this.inner.poll(cx) {
            Poll::Ready(v) => Poll::Ready(Some(v)),
            Poll::Pending => Poll::Pending,
        }
    }
}

use tokio::pin;

let long_op = some_slow_task();
pin!(long_op); // 現在 long_op 是 Pin<&mut impl Future>

loop {
    tokio::select! {
        result = &mut long_op => { // &mut 在這裡做的正是 reborrow
            println!("完成：{:?}", result);
            break;
        }
        _ = tokio::time::sleep(Duration::from_secs(1)) => {
            println!("還在等...");
        }
    }
}

#[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
}