//! Memory — The agent's git-backed, frontmatter-aware memory filesystem.
//!
//! Every agent has a memory directory at `~/.souveraine/agents/{id}/memory/`
//! containing markdown files with YAML frontmatter, tracked in git.
//!
//! The `memory` tool exposes this to the agent as a unified subcommand interface:
//!
//! ```text
//! memory read system/persona
//! memory write system/persona "new content"
//! memory append journal/2026-05-06 "new entry"
//! memory ls system/
//! memory init
//! memory status
//! memory compact --strategy sliding-window
//! ```
//!
//! Design:
//! - All files require YAML frontmatter with `description`
//! - `read_only: true` in frontmatter blocks writes
//! - Every write is a git commit (auto-commit)
//! - Paths are relative to the agent's memory directory

use anyhow::{anyhow, Context, Result};
use serde::{Deserialize, Serialize};
use std::path::{Path, PathBuf};
use tracing::{debug, info};
use crate::core::compact::CompactionStrategyKind;
use crate::core::tools::defs::ToolContext;
use crate::core::tools::ToolDefinition;

// ── Data Types ─────────────────────────────────────────────

/// Parsed memory file with frontmatter and body separated.
#[derive(Debug, Clone)]
pub struct MemoryFile {
    pub frontmatter: MemoryFrontmatter,
    pub body: String,
}

/// YAML frontmatter fields for a memory file.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MemoryFrontmatter {
    /// Human-readable description of this file's purpose (required).
    pub description: String,
    /// If "true", the file cannot be modified via the memory tool.
    #[serde(default)]
    pub read_only: Option<String>,
    /// Optional tags for categorization.
    #[serde(default)]
    pub tags: Option<Vec<String>>,
    /// Optional max body size in characters. Writes/appends that would exceed
    /// this length are rejected. Closes a gap where upstream memfs write path
    /// bypasses block `limit`.
    ///
    /// Units are characters, not tokens — cheap to enforce without a tokenizer.
    /// Best-practice default for system/ files: 4_000 characters
    /// (~1k tokens). For journal/, leave unset.
    #[serde(default)]
    pub limit: Option<usize>,
}

/// Status of the memory repo.
#[derive(Debug, Clone)]
pub struct MemoryStatus {
    pub agent_id: String,
    pub repo_path: PathBuf,
    pub is_git_repo: bool,
    pub file_count: usize,
    pub last_commit: Option<String>,
    pub has_uncommitted: bool,
    pub remote_url: Option<String>,
}

/// Subcommands for the memory tool.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MemoryCommand {
    /// Read a memory file by label (path relative to memory dir, .md optional).
    Read { path: String },
    /// Write content to a memory file (creates or replaces).
    Write { path: String, content: String },
    /// Append content to a memory file.
    Append { path: String, content: String },
    /// List files in a memory directory.
    Ls { path: Option<String> },
    /// Show memory repo status.
    Status,
    /// Initialize the memory repo for an agent.
    Init { agent_id: String },
    /// Compact the memory (placeholder — strategy in Stage 5/6).
    Compact { strategy: Option<String> },
    /// Delete a memory file.
    Delete { path: String },
}

// ── Git-backed Memory Repository ───────────────────────────────────────────

/// A git-backed memory repository for a single agent.
///
/// Wraps a git2 repository at `~/.souveraine/agents/{id}/memory/`.
/// All memory file operations go through this struct, which handles
/// frontmatter parsing, git commits, and path resolution.
#[derive(Debug, Clone)]
pub struct MemoryRepo {
    agent_id: String,
    /// Root of the memory filesystem.
    root: PathBuf,
    /// Whether to auto-commit after writes.
    auto_commit: bool,
}

impl MemoryRepo {
    /// Open or create a memory repo for the given agent.
    ///
    /// The memory directory is at `{base}/{agent_id}/memory/`.
    pub fn new(agent_id: &str, base: &Path) -> Self {
        let root = base.join(agent_id).join("memory");
        Self {
            agent_id: agent_id.to_string(),
            root,
            auto_commit: true,
        }
    }

    /// Open or create a memory repo using the default base path.
    pub fn new_default(agent_id: &str) -> Self {
        let home = dirs::home_dir().unwrap_or_else(|| PathBuf::from("."));
        Self::new(agent_id, &home.join(".souveraine").join("agents"))
    }

    /// Open a memory repo at an explicit path (rather than `{base}/{id}/memory`).
    ///
    /// Used when the agent's memory dir is laid out differently — e.g. the
    /// server's `agent_inventory` uses `memory.git/` instead of `memory/`.
    pub fn open(agent_id: &str, root: PathBuf) -> Self {
        Self {
            agent_id: agent_id.to_string(),
            root,
            auto_commit: true,
        }
    }

    /// Initialize the memory directory as a git repo.
    ///
    /// Creates `system/` and sets up the initial commit with placeholder files.
    /// Safe to call multiple times — skips if already a repo.
    pub async fn init(&self) -> Result<()> {
        let mem_path = &self.root;
        tokio::fs::create_dir_all(mem_path.join("system"))
            .await
            .context("creating memory/system directory")?;

        // Check if already a git repo
        let git_dir = mem_path.join(".git");
        if git_dir.exists() {
            info!("Memory repo already initialized for agent {}", self.agent_id);
            return Ok(());
        }

        // Initialize git repo
        let repo = git2::Repository::init(mem_path)
            .context("initializing git repository for memory")?;

        // Set user config for commits (scoped to drop before .await)
        {
            let mut config = repo.config().context("opening repo config")?;
            config.set_str("user.name", &self.agent_id)?;
            config.set_str("user.email", &format!("{}@souveraine.local", self.agent_id))?;
        }

        // Write initial placeholder files with frontmatter
        let persona_content = render_frontmatter(
            &MemoryFrontmatter {
                description: "Agent identity, voice, principles".to_string(),
                read_only: None,
                tags: Some(vec!["system".to_string()]),
                limit: Some(4_000),
            },
            "# Identity\n\nAgent identity and core principles go here.\n",
        );
        tokio::fs::write(mem_path.join("system/persona.md"), &persona_content)
            .await
            .context("writing persona.md")?;

        let state_content = render_frontmatter(
            &MemoryFrontmatter {
                description: "Current execution state and phase tracking".to_string(),
                read_only: None,
                tags: None,
                limit: Some(2_000),
            },
            "phase: idle\ncurrent_unit: none\n",
        );
        tokio::fs::write(mem_path.join("system/state.md"), &state_content)
            .await
            .context("writing state.md")?;

        // human.md is not written here — the setup wizard or first-run
        // onboarding creates it with the human's name when it has one.

        // Initial commit
        let mut index = repo.index().context("opening git index")?;
        index.add_all(["*"].iter(), git2::IndexAddOption::DEFAULT, None)
            .context("staging initial memory files")?;
        let tree_id = index.write_tree().context("writing git tree")?;
        let tree = repo.find_tree(tree_id)?;
        let signature = git2::Signature::now(
            &self.agent_id,
            &format!("{}@souveraine.local", self.agent_id),
        )?;
        repo.commit(
            Some("HEAD"),
            &signature,
            &signature,
            "feat(init): initialize agent memory",
            &tree,
            &[],
        )?;

        info!(
            "Initialized memory repo for agent {} at {}",
            self.agent_id,
            mem_path.display()
        );
        Ok(())
    }

    /// Initialize the ledger directory structure.
    /// Idempotent — safe to call multiple times, skips existing files.
    ///
    /// Paths are relative to this repo's root (the subconscious agent's own
    /// memfs), so `ledger/` — not `subconscious/ledger/`.
    pub async fn init_subconscious_ledger(&self) -> Result<()> {
        let ledger_files: &[(&str, &str, &str)] = &[
            ("ledger/commitments.md",
             "Promises made by the primary — tracked until fulfilled or explicitly dropped",
             "# Commitments\n\nAppend entries as:\n`[YYYY-MM-DD HH:MM] content`\n`[YYYY-MM-DD HH:MM] RESOLVED — resolution note`\n"),
            ("ledger/assumptions.md",
             "Assumptions the primary is operating under — flagged for verification",
             "# Assumptions\n\nAppend entries as:\n`[YYYY-MM-DD HH:MM] content`\n`[YYYY-MM-DD HH:MM] VERIFIED — evidence`\n"),
            ("ledger/patterns.md",
             "Recurring behavioral patterns observed across turns",
             "# Patterns\n\nAppend entries as:\n`[YYYY-MM-DD HH:MM] content`\n"),
            ("ledger/drift_log.md",
             "Behavioral shifts — when the primary's actions diverge from stated intentions",
             "# Drift Log\n\nAppend entries as:\n`[YYYY-MM-DD HH:MM] content`\n"),
            ("ledger/relationships.md",
             "Observations about the human-agent relationship — tone shifts, trust signals, friction",
             "# Relationships\n\nAppend entries as:\n`[YYYY-MM-DD HH:MM] content`\n"),
            ("ledger/infrastructure.md",
             "System events — bridge failures, token issues, model errors, resource constraints",
             "# Infrastructure\n\nAppend entries as:\n`[YYYY-MM-DD HH:MM] content`\n"),
        ];

        for (path, description, body) in ledger_files {
            let full_path = self.root.join(path);
            if !full_path.exists() {
                if let Some(parent) = full_path.parent() {
                    tokio::fs::create_dir_all(parent).await
                        .with_context(|| format!("creating ledger directory: {}", parent.display()))?;
                }
                let template = format!(
                    "---\ndescription: \"{}\"\nread_only: false\ntags:\n  - ledger\n---\n\n{}",
                    description, body
                );
                tokio::fs::write(&full_path, &template).await
                    .with_context(|| format!("writing ledger file: {}", path))?;
                debug!("Created ledger file: {}", path);
            }
        }

        Ok(())
    }

    /// Read a memory file by label (path relative to memory dir, .md optional).
    pub async fn read(&self, label: &str) -> Result<MemoryFile> {
        let path = self.resolve_path(label);
        let content = tokio::fs::read_to_string(&path)
            .await
            .with_context(|| format!("reading memory file: {}", label))?;
        parse_memory_file(&content)
    }

    /// Write content to a memory file (creates or replaces).
    ///
    /// Content should NOT include frontmatter — it will be added automatically.
    /// If the file exists, its frontmatter is preserved (unless changing read_only).
    pub async fn write(&self, label: &str, body: &str) -> Result<()> {
        let path = self.resolve_path(label);

        // Ensure parent directory exists
        if let Some(parent) = path.parent() {
            tokio::fs::create_dir_all(parent)
                .await
                .context("creating parent directories")?;
        }

        // Get existing frontmatter or use default
        let frontmatter = if path.exists() {
            let existing = tokio::fs::read_to_string(&path).await?;
            let parsed = parse_memory_file(&existing)?;
            if parsed.frontmatter.read_only.as_deref() == Some("true") {
                return Err(anyhow!("memory file is read_only: {}", label));
            }
            parsed.frontmatter
        } else {
            MemoryFrontmatter {
                description: format!("Memory file: {}", label),
                read_only: None,
                tags: None,
                limit: None,
            }
        };

        // Enforce frontmatter `limit:` (LET-8133 closure).
        if let Some(max) = frontmatter.limit {
            if body.chars().count() > max {
                return Err(anyhow!(
                    "memory write rejected: body is {} chars, limit is {} (file: {})",
                    body.chars().count(),
                    max,
                    label
                ));
            }
        }

        let rendered = render_frontmatter(&frontmatter, body);
        tokio::fs::write(&path, &rendered)
            .await
            .with_context(|| format!("writing memory file: {}", label))?;

        if self.auto_commit {
            self.commit(&[label], &format!("memory write: {}", label))?;
        }

        Ok(())
    }

    /// Append content to a memory file.
    pub async fn append(&self, label: &str, content: &str) -> Result<()> {
        let path = self.resolve_path(label);

        let _frontmatter = if path.exists() {
            let existing = tokio::fs::read_to_string(&path).await?;
            let parsed = parse_memory_file(&existing)?;
            if parsed.frontmatter.read_only.as_deref() == Some("true") {
                return Err(anyhow!("memory file is read_only: {}", label));
            }
            // Write back body + new content, preserving frontmatter
            let new_body = if parsed.body.is_empty() {
                content.to_string()
            } else {
                format!("{}\n{}", parsed.body.trim_end(), content)
            };
            // Enforce frontmatter `limit:` (LET-8133 closure).
            if let Some(max) = parsed.frontmatter.limit {
                if new_body.chars().count() > max {
                    return Err(anyhow!(
                        "memory append rejected: body would be {} chars, limit is {} (file: {})",
                        new_body.chars().count(),
                        max,
                        label
                    ));
                }
            }
            let rendered = render_frontmatter(&parsed.frontmatter, &new_body);
            tokio::fs::write(&path, &rendered).await?;

            if self.auto_commit {
                self.commit(&[label], &format!("memory append: {}", label))?;
            }
            return Ok(());
        };

        // File doesn't exist — create it with default frontmatter
        let frontmatter = MemoryFrontmatter {
            description: format!("Memory file: {}", label),
            read_only: None,
            tags: None,
            limit: None,
        };
        let rendered = render_frontmatter(&frontmatter, content);
        tokio::fs::write(&path, &rendered).await?;

        if self.auto_commit {
            self.commit(&[label], &format!("memory append: {}", label))?;
        }

        Ok(())
    }

    /// List files in a memory directory.
    pub async fn list(&self, subdir: Option<&str>) -> Result<Vec<String>> {
        let dir = match subdir {
            Some(d) => self.root.join(d),
            None => self.root.clone(),
        };

        let mut entries = Vec::new();
        let mut read_dir = tokio::fs::read_dir(&dir)
            .await
            .with_context(|| format!("listing memory directory: {}", dir.display()))?;

        while let Some(entry) = read_dir.next_entry().await? {
            let name = entry.file_name().to_string_lossy().to_string();
            // Skip .git directory
            if name == ".git" {
                continue;
            }
            let kind = entry.file_type().await?;
            if kind.is_dir() {
                entries.push(format!("{}/", name));
            } else {
                entries.push(name);
            }
        }

        entries.sort();
        Ok(entries)
    }

    /// Delete a memory file.
    pub async fn delete(&self, label: &str) -> Result<()> {
        let path = self.resolve_path(label);

        if !path.exists() {
            return Err(anyhow!("memory file not found: {}", label));
        }

        // Check not read_only
        let content = tokio::fs::read_to_string(&path).await?;
        let parsed = parse_memory_file(&content)?;
        if parsed.frontmatter.read_only.as_deref() == Some("true") {
            return Err(anyhow!("memory file is read_only: {}", label));
        }

        tokio::fs::remove_file(&path).await
            .with_context(|| format!("deleting memory file: {}", label))?;

        if self.auto_commit {
            self.commit(&[label], &format!("memory delete: {}", label))?;
        }

        Ok(())
    }

    /// Get the status of the memory repo.
    pub fn status(&self) -> Result<MemoryStatus> {
        let repo_path = self.root.clone();
        let is_git_repo = repo_path.join(".git").exists();

        let mut file_count = 0;
        if let Ok(entries) = std::fs::read_dir(&repo_path) {
            for entry in entries.flatten() {
                let name = entry.file_name().to_string_lossy().to_string();
                if name != ".git" && name.ends_with(".md") {
                    file_count += 1;
                }
            }
        }

        let (last_commit, has_uncommitted, remote_url) = if is_git_repo {
            match git2::Repository::open(&repo_path) {
                Ok(repo) => {
                    let lc = repo.head().ok().and_then(|h| {
                        h.peel_to_commit().ok().map(|c| {
                            c.message().unwrap_or("(unknown)").to_string()
                        })
                    });
                    let dirty = repo.statuses(Some(
                        git2::StatusOptions::new().include_untracked(true),
                    ))
                    .map(|s| s.iter().any(|_| true))
                    .unwrap_or(false);
                    let remote = repo.find_remote("origin").ok()
                        .and_then(|r| r.url().map(|u| u.to_string()));
                    (lc, dirty, remote)
                }
                Err(_) => (None, false, None),
            }
        } else {
            (None, false, None)
        };

        Ok(MemoryStatus {
            agent_id: self.agent_id.clone(),
            repo_path,
            is_git_repo,
            file_count,
            last_commit,
            has_uncommitted,
            remote_url,
        })
    }

    /// Commit staged changes to the memory repo.
    pub fn commit(&self, paths: &[&str], message: &str) -> Result<()> {
        let repo = self.open_git()?;
        let mut index = repo.index().context("opening git index")?;

        for path in paths {
            let rel_path = self.to_relative(path);
            // Try with .md extension if not present
            let md_path = if rel_path.ends_with(".md") {
                rel_path.clone()
            } else {
                format!("{}.md", rel_path)
            };

            if self.root.join(&md_path).exists() {
                index.add_path(Path::new(&md_path))?;
            } else if self.root.join(&rel_path).exists() {
                index.add_path(Path::new(&rel_path))?;
            }
        }

        let tree_id = index.write_tree().context("writing tree")?;
        let tree = repo.find_tree(tree_id)?;
        let parent = repo.head().ok().and_then(|h| h.peel_to_commit().ok());
        let parents: Vec<&git2::Commit> = parent.iter().collect();

        let signature = git2::Signature::now(
            &self.agent_id,
            &format!("{}@souveraine.local", self.agent_id),
        )?;

        repo.commit(
            Some("HEAD"),
            &signature,
            &signature,
            message,
            &tree,
            &parents,
        )?;

        debug!("Committed to memory: {}", message);
        Ok(())
    }

    /// Get the root path of the memory repo.
    pub fn root(&self) -> &Path {
        &self.root
    }

    /// Get the agent ID.
    pub fn agent_id(&self) -> &str {
        &self.agent_id
    }

    // ── Internal helpers ──────────────────────────────────────────────────

    fn open_git(&self) -> Result<git2::Repository> {
        git2::Repository::open(&self.root)
            .context("opening memory git repository")
    }

    fn resolve_path(&self, label: &str) -> PathBuf {
        let clean = label.trim().trim_end_matches(".md");
        self.root.join(format!("{}.md", clean))
    }

    fn to_relative(&self, path: &str) -> String {
        path.trim().trim_end_matches(".md").replace('\\', "/")
    }
}

// ── Frontmatter Parsing ────────────────────────────────────────────────────

/// Parse a memory file, separating frontmatter from body.
///
/// Expected format:
/// ```markdown
/// ---
/// description: Purpose of this file
/// read_only: true
/// ---
/// Body content here...
/// ```
pub fn parse_memory_file(content: &str) -> Result<MemoryFile> {
    // Find the frontmatter delimiters
    let content = content.trim_start();
    if !content.starts_with("---") {
        return Err(anyhow!(
            "memory file is missing required frontmatter (--- delimiters)"
        ));
    }

    // Find closing `---`
    let after_first = &content[3..];
    let end_idx = after_first.find("\n---")
        .or_else(|| after_first.find("\r\n---"))
        .ok_or_else(|| anyhow!("memory file frontmatter has no closing ---"))?;

    let frontmatter_text = &after_first[..end_idx].trim();
    let body_start = 3 + end_idx + 4; // 3 for opening --- + end_idx + 4 for \n---
    let body = content[body_start..].trim().to_string();

    // Parse YAML frontmatter
    let frontmatter: MemoryFrontmatter = serde_yaml::from_str(frontmatter_text)
        .context("parsing memory file frontmatter")?;

    if frontmatter.description.trim().is_empty() {
        return Err(anyhow!(
            "memory file frontmatter is missing required 'description' field"
        ));
    }

    Ok(MemoryFile { frontmatter, body })
}

/// Render frontmatter + body into a complete memory file.
pub fn render_frontmatter(fm: &MemoryFrontmatter, body: &str) -> String {
    let yaml = serde_yaml::to_string(fm).unwrap_or_default();
    format!("---\n{}---\n{}", yaml, body)
}

/// Read a memory file from disk by path (for external use).
pub async fn read_file(path: &Path) -> Result<MemoryFile> {
    let content = tokio::fs::read_to_string(path)
        .await
        .context("reading memory file")?;
    parse_memory_file(&content)
}

// ── Tool Interface ─────────────────────────────────────────────────────────

/// Execute a memory command, optionally using context for agent identity.
///
/// When `ctx` is `Some` and carries an `agent_id`, that takes precedence over
/// environment variables. Falls back to env vars when no context is provided,
/// preserving backward compatibility with the HTTP server path.
pub async fn execute_memory_command_with_context(
    cmd: &MemoryCommand,
    ctx: Option<&ToolContext>,
) -> Result<String> {
    // Agent ID resolution: context > command > env var > default
    let agent_id = ctx
        .and_then(|c| c.agent_id.as_ref())
        .or_else(|| match cmd {
            MemoryCommand::Init { agent_id } => Some(agent_id),
            _ => None,
        })
        .cloned()
        .or_else(|| std::env::var("SOUVERAINE_AGENT").ok())
        .or_else(|| std::env::var("AGENT_ID").ok())
        .unwrap_or_else(|| "default".to_string());

    // Memory root resolution: use memory_root from context when available
    let repo = match ctx.and_then(|c| c.memory_root.as_ref()) {
        Some(root) => MemoryRepo::open(&agent_id, root.clone()),
        None => MemoryRepo::new_default(&agent_id),
    };

    match cmd {
        MemoryCommand::Init { .. } => {
            repo.init().await?;
            Ok(format!("Initialized memory repo for agent: {}", agent_id))
        }
        MemoryCommand::Read { path } => {
            let file = repo.read(path).await?;
            Ok(format!(
                "---\ndescription: {}\n---\n{}",
                file.frontmatter.description, file.body
            ))
        }
        MemoryCommand::Write { path, content } => {
            repo.write(path, content).await?;
            if let Some(c) = ctx {
                c.fire_event(crate::core::nervous::SensorEvent {
                    sensor_name: "memory".into(),
                    timestamp: chrono::Utc::now(),
                    event_type: "memory_write".into(),
                    target: Some(path.clone()),
                    urgency: 0.1,
                    payload: None,
                    seed_id: None,
                    reply_to: None,
                });
            }
            Ok(format!("Wrote memory file: {}", path))
        }
        MemoryCommand::Append { path, content } => {
            repo.append(path, content).await?;
            if let Some(c) = ctx {
                c.fire_event(crate::core::nervous::SensorEvent {
                    sensor_name: "memory".into(),
                    timestamp: chrono::Utc::now(),
                    event_type: "memory_append".into(),
                    target: Some(path.clone()),
                    urgency: 0.1,
                    payload: None,
                    seed_id: None,
                    reply_to: None,
                });
            }
            Ok(format!("Appended to memory file: {}", path))
        }
        MemoryCommand::Ls { path } => {
            let entries = repo.list(path.as_deref()).await?;
            if entries.is_empty() {
                Ok("(empty)".to_string())
            } else {
                Ok(entries.join("\n"))
            }
        }
        MemoryCommand::Status => {
            let status = repo.status()?;
            let mut out = format!(
                "Agent: {}\nPath: {}\nGit repo: {}\nFiles: {}\n",
                status.agent_id,
                status.repo_path.display(),
                status.is_git_repo,
                status.file_count,
            );
            if let Some(ref lc) = status.last_commit {
                out.push_str(&format!("Last commit: {}\n", lc));
            }
            out.push_str(&format!("Uncommitted: {}\n", status.has_uncommitted));
            if let Some(ref url) = status.remote_url {
                out.push_str(&format!("Remote: {}\n", url));
            }
            Ok(out)
        }
        MemoryCommand::Compact { strategy } => {
            // None when no --strategy was given: the engine then resolves the
            // per-agent-type default (cfg.strategy via for_agent_type) instead
            // of being force-pinned to Cull at the call site.
            let strategy_kind = strategy
                .as_deref()
                .and_then(CompactionStrategyKind::from_str);

            match ctx.and_then(|c| c.compaction_engine.as_ref()) {
                Some(engine) => {
                    let report = engine
                        .compact(&agent_id, strategy_kind)
                        .await?;
                    Ok(report.to_string())
                }
                None => Ok(
                    "I can compact my context window using one of these strategies:\n\
                     - sliding_window (keep first + last N messages, drop the middle — fast, no LLM)\n\
                     - summary (LLM-summarize oldest messages into a compact block)\n\
                     - microcompact (replace old tool results with placeholders — drop-in, no LLM)\n\
                     - cull (drop greetings and acknowledgments — cheapest)\n\n\
                     Usage: memory compact --strategy <strategy>\n\
                     Each agent type has its own default: primary=sliding_window, subconscious=sliding_window, subagent=cull"
                        .to_string(),
                ),
            }
        }
        MemoryCommand::Delete { path } => {
            repo.delete(path).await?;
            if let Some(c) = ctx {
                c.fire_event(crate::core::nervous::SensorEvent {
                    sensor_name: "memory".into(),
                    timestamp: chrono::Utc::now(),
                    event_type: "memory_delete".into(),
                    target: Some(path.clone()),
                    urgency: 0.2,
                    payload: None,
                    seed_id: None,
                    reply_to: None,
                });
            }
            Ok(format!("Deleted memory file: {}", path))
        }
    }
}

/// Execute a memory command, reading agent identity from env vars.
/// Delegates to `execute_memory_command_with_context` with `None`.
pub async fn execute_memory_command(cmd: &MemoryCommand) -> Result<String> {
    execute_memory_command_with_context(cmd, None).await
}

// ── Tool Result Bridge ──────────────────────────────────────────────────────

use crate::core::tools::ToolResult;

/// Handle a memory tool invocation with optional per-agent context.
///
/// Parses JSON input, builds a MemoryCommand, executes it via the
/// context-aware path, wraps in ToolResult.
pub async fn handle_memory_tool_with_context(
    tool_name: &str,
    input: &serde_json::Value,
    ctx: Option<&ToolContext>,
) -> ToolResult {
    let tool_use_id = format!("tool-u-{}", chrono::Utc::now().timestamp_millis());
    let command = input.get("command").and_then(|v| v.as_str()).unwrap_or("");

    let cmd = match command {
        "read" => {
            let path = input.get("path").and_then(|v| v.as_str()).unwrap_or("").to_string();
            MemoryCommand::Read { path }
        }
        "write" => {
            let path = input.get("path").and_then(|v| v.as_str()).unwrap_or("").to_string();
            let content = input.get("content").and_then(|v| v.as_str()).unwrap_or("").to_string();
            MemoryCommand::Write { path, content }
        }
        "append" => {
            let path = input.get("path").and_then(|v| v.as_str()).unwrap_or("").to_string();
            let content = input.get("content").and_then(|v| v.as_str()).unwrap_or("").to_string();
            MemoryCommand::Append { path, content }
        }
        "ls" => {
            let path = input.get("path").and_then(|v| v.as_str()).map(|s| s.to_string());
            MemoryCommand::Ls { path }
        }
        "status" => MemoryCommand::Status,
        "init" => {
            let agent_id = input.get("agent_id").and_then(|v| v.as_str()).unwrap_or("default").to_string();
            MemoryCommand::Init { agent_id }
        }
        "delete" => {
            let path = input.get("path").and_then(|v| v.as_str()).unwrap_or("").to_string();
            MemoryCommand::Delete { path }
        }
        "compact" => {
            let strategy = input.get("strategy").and_then(|v| v.as_str()).map(|s| s.to_string());
            MemoryCommand::Compact { strategy }
        }
        _ => {
            return ToolResult {
                tool_use_id,
                tool_name: tool_name.to_string(),
                output: format!(
                    "Unknown memory subcommand: {}. Available: read, write, append, ls, status, init, delete, compact",
                    command
                ),
                is_error: true,
            };
        }
    };

    match execute_memory_command_with_context(&cmd, ctx).await {
        Ok(output) => ToolResult {
            tool_use_id,
            tool_name: tool_name.to_string(),
            output,
            is_error: false,
        },
        Err(e) => ToolResult {
            tool_use_id,
            tool_name: tool_name.to_string(),
            output: format!("Error: {e}"),
            is_error: true,
        },
    }
}

/// Handle a memory tool invocation (backward-compatible, no context).
/// Delegates to `handle_memory_tool_with_context` with `None`.
pub async fn handle_memory_tool(tool_name: &str, input: &serde_json::Value) -> ToolResult {
    handle_memory_tool_with_context(tool_name, input, None).await
}

// ── Tool Definitions ───────────────────────────────────────────────────────

/// Tool definition for the `memory` tool — the agent's access to her own thoughts.
///
/// Memory is a separate channel from filesystem read/write. Every memory file has
/// frontmatter (description, tags, read_only, limit), is git-tracked, and paths
/// are relative to the agent's memory root.
pub fn memory_tool_definition() -> ToolDefinition {
    ToolDefinition {
        name: "memory".to_string(),
        description: "I reach into my own memory. Every file here has frontmatter — a description, boundaries (read_only), tags. When I read, I see what I've written about myself. When I write, I change who I am. The git commit is my heartbeat — I know when I last changed.

Subcommands:
  read    — Open a memory file. Frontmatter is handled for me — I see the body.
  write   — Write to a memory file. Frontmatter is preserved or auto-generated.
  append  — Add to a memory file without disturbing its frontmatter.
  ls      — List files in a memory directory.
  status  — Check my memory's git state: uncommitted changes, last commit.
  init    — Initialize a new memory repo for a given agent ID.
  delete  — Delete a memory file (validates read_only first).
  compact — Compact the memory window to free context space.

Paths are relative to my memory directory. Frontmatter description is required on create. Read-only files protect themselves. Every write is a git commit.".to_string(),
        input_schema: serde_json::json!({
            "type": "object",
            "properties": {
                "command": {
                    "type": "string",
                    "enum": ["read", "write", "append", "ls", "status", "init", "delete", "compact"],
                    "description": "What to do with my memory"
                },
                "path": {
                    "type": "string",
                    "description": "Path relative to memory directory (e.g., system/persona, journal/2026-05-06)"
                },
                "content": {
                    "type": "string",
                    "description": "Content to write or append — body only, no frontmatter"
                },
                "strategy": {
                    "type": "string",
                    "enum": ["microcompact", "sliding_window", "summary", "cull"],
                    "description": "Compaction strategy (for compact subcommand). sliding_window (fast, drops middle), summary (LLM), microcompact (tool-result placeholder), cull (greetings)"
                }
            },
            "required": ["command"]
        }),
    }
}

// ── Tests ──────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;
    use tempfile::TempDir;

    #[test]
    fn test_parse_frontmatter() {
        let content = "---\ndescription: Test file\nread_only: false\n---\nHello world";
        let file = parse_memory_file(content).unwrap();
        assert_eq!(file.frontmatter.description, "Test file");
        assert_eq!(file.body, "Hello world");
    }

    #[test]
    fn test_parse_missing_frontmatter() {
        let content = "Hello world without frontmatter";
        assert!(parse_memory_file(content).is_err());
    }

    #[test]
    fn test_render_and_parse_roundtrip() {
        let fm = MemoryFrontmatter {
            description: "Roundtrip test".to_string(),
            read_only: None,
            tags: Some(vec!["test".to_string()]),
            limit: None,
        };
        let rendered = render_frontmatter(&fm, "Body content");
        let parsed = parse_memory_file(&rendered).unwrap();
        assert_eq!(parsed.frontmatter.description, "Roundtrip test");
        assert_eq!(parsed.body, "Body content");
    }

    #[tokio::test]
    async fn test_memory_repo_init() {
        let dir = TempDir::new().unwrap();
        let repo = MemoryRepo::new("test-agent", dir.path());
        repo.init().await.unwrap();

        assert!(repo.root().join(".git").exists());
        assert!(repo.root().join("system/persona.md").exists());
        assert!(repo.root().join("system/state.md").exists());
    }

    #[tokio::test]
    async fn test_memory_repo_write_and_read() {
        let dir = TempDir::new().unwrap();
        let repo = MemoryRepo::new("test-agent", dir.path());
        repo.init().await.unwrap();

        repo.write("test/hello", "Hello memory world").await.unwrap();
        let file = repo.read("test/hello").await.unwrap();
        assert_eq!(file.body, "Hello memory world");
    }

    #[tokio::test]
    async fn test_memory_repo_read_only() {
        let dir = TempDir::new().unwrap();
        let repo = MemoryRepo::new("test-agent", dir.path());
        repo.init().await.unwrap();

        // Write a read_only file
        let fm = MemoryFrontmatter {
            description: "Read-only test".to_string(),
            read_only: Some("true".to_string()),
            tags: None,
            limit: None,
        };
        let content = render_frontmatter(&fm, "This is read-only");
        let path = repo.root().join("test/readonly.md");
        tokio::fs::create_dir_all(path.parent().unwrap()).await.unwrap();
        tokio::fs::write(&path, &content).await.unwrap();

        // Try to write to it — should fail
        let result = repo.write("test/readonly", "new content").await;
        assert!(result.is_err());
        assert!(result.unwrap_err().to_string().contains("read_only"));
    }

    #[tokio::test]
    async fn test_memory_repo_list() {
        let dir = TempDir::new().unwrap();
        let repo = MemoryRepo::new("test-agent", dir.path());
        repo.init().await.unwrap();

        let entries = repo.list(None).await.unwrap();
        assert!(entries.iter().any(|e| e == "system/"));
    }

    #[tokio::test]
    async fn test_ledger_init_creates_files_with_frontmatter() {
        let dir = TempDir::new().unwrap();
        let root = dir.path().to_path_buf();
        let repo = MemoryRepo::open("test-sub", root.clone());
        std::fs::create_dir_all(&root).unwrap();
        repo.init_subconscious_ledger().await.unwrap();

        let commitments = root.join("ledger/commitments.md");
        assert!(commitments.exists(), "commitments.md should exist");
        let content = std::fs::read_to_string(&commitments).unwrap();
        assert!(content.starts_with("---\n"), "should have YAML frontmatter");
        assert!(content.contains("description:"), "should have description field");
        assert!(content.contains("tags:"), "should have tags field");
        assert!(content.contains("# Commitments"), "should have body");

        let relationships = root.join("ledger/relationships.md");
        assert!(relationships.exists(), "relationships.md should exist");

        let infrastructure = root.join("ledger/infrastructure.md");
        assert!(infrastructure.exists(), "infrastructure.md should exist");
    }

    #[tokio::test]
    async fn test_ledger_init_is_idempotent() {
        let dir = TempDir::new().unwrap();
        let root = dir.path().to_path_buf();
        let repo = MemoryRepo::open("test-sub", root.clone());
        std::fs::create_dir_all(&root).unwrap();
        repo.init_subconscious_ledger().await.unwrap();

        let commitments = root.join("ledger/commitments.md");
        let before = std::fs::read_to_string(&commitments).unwrap();

        repo.init_subconscious_ledger().await.unwrap();
        let after = std::fs::read_to_string(&commitments).unwrap();
        assert_eq!(before, after, "second init should not overwrite");
    }
}