swarm_engine_core/

actions.rs

//! Actions 統一管理
//!
//! Orchestrator 内で使用される Action を Protocol として統一管理する。
//! Group 機能により、コンテキストに応じた Action セットを取得できる。
//!
//! # 設計
//!
//! ```text
//! ActionsConfig
//! ├─ actions: HashMap<String, ActionDef>
//! │   └─ "read_file" → ActionDef { groups: ["file_ops", "exploration"] }
//! │   └─ "grep"      → ActionDef { groups: ["search", "exploration"] }
//! │   └─ "write"     → ActionDef { groups: ["file_ops", "mutation"] }
//! │
//! └─ groups: HashMap<String, ActionGroup>
//!     └─ "readonly"  → ActionGroup { include: ["exploration"], exclude: ["mutation"] }
//!     └─ "all"       → ActionGroup { include: ["*"] }
//! ```
//!
//! # 使用例
//!
//! ```ignore
//! // 構築
//! let cfg = ActionsConfig::new()
//!     .action("read_file", ActionDef::new("ファイル読み込み").groups(["file_ops", "exploration"]))
//!     .action("grep", ActionDef::new("パターン検索").groups(["search", "exploration"]))
//!     .group("readonly", ActionGroup::include(["exploration"]).exclude(["mutation"]));
//!
//! // Extensions に登録
//! let orc = OrchestratorBuilder::new()
//!     .extension(cfg)
//!     .build(runtime);
//!
//! // Manager から使用
//! let cfg = state.shared.extensions.get::<ActionsConfig>()?;
//! let candidates = cfg.candidates_for("readonly");  // → ["read_file", "grep"]
//! ```

use std::collections::HashMap;
use std::time::Duration;

use serde::{Deserialize, Serialize};

// ============================================================================
// Action Types
// ============================================================================

/// Action のカテゴリ（探索空間への影響で分類）
///
/// # カテゴリ説明
///
/// - **NodeExpand**: 新しい探索対象を発見する（例: Grep, List）
///   - 成功時: 発見した対象を新しい Node として追加
///   - 探索グラフが拡張される
///
/// - **NodeStateChange**: 既存 Node の状態を遷移させる（例: Read）
///   - 成功時: 既存 Node の状態を Explored/Completed に更新
///   - 探索グラフは拡張されない
///
/// # 例: ファイル探索タスク
///
/// ```text
/// Grep("auth") [NodeExpand]
///   → 発見: src/auth.rs → 新 Node 追加
///
/// Read("src/auth.rs") [NodeStateChange]
///   → src/auth.rs Node の状態を Explored に更新
///   → 目標ファイルなら Completed
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
pub enum ActionCategory {
    /// 新しい探索対象を発見する（Grep, List など）
    #[default]
    NodeExpand,
    /// 既存 Node の状態を遷移させる（Read など）
    NodeStateChange,
}

/// Action - Agent が実行する処理
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Action {
    pub name: String,
    pub params: ActionParams,
}

/// Action パラメータ
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ActionParams {
    /// ターゲット（ファイルパス等）
    pub target: Option<String>,
    /// 引数
    pub args: HashMap<String, String>,
    /// 生データ
    pub data: Vec<u8>,
}

// ============================================================================
// ActionOutput - 型付き出力表現
// ============================================================================

/// Action 出力の型付き表現
///
/// `Box<dyn Any>` の代わりに明示的な型を使用することで:
/// - Clone 可能
/// - パターンマッチで安全なアクセス
/// - 下流処理が明確化
#[derive(Debug, Clone)]
pub enum ActionOutput {
    /// プレーンテキスト出力（stdout、ファイル内容、メッセージ等）
    Text(String),

    /// 構造化データ出力（観測結果、クエリ結果等）
    Structured(serde_json::Value),

    /// バイナリ出力（画像、ファイル等、将来用）
    Binary(Vec<u8>),
}

impl ActionOutput {
    /// テキストとして取得（Structured は JSON 文字列化）
    pub fn as_text(&self) -> String {
        match self {
            Self::Text(s) => s.clone(),
            Self::Structured(v) => v.to_string(),
            Self::Binary(b) => format!("<binary: {} bytes>", b.len()),
        }
    }

    /// 構造化データとして取得（Text は parse 試行）
    pub fn as_structured(&self) -> Option<serde_json::Value> {
        match self {
            Self::Text(s) => serde_json::from_str(s).ok(),
            Self::Structured(v) => Some(v.clone()),
            Self::Binary(_) => None,
        }
    }

    /// テキスト参照を取得（Text の場合のみ）
    pub fn text(&self) -> Option<&str> {
        match self {
            Self::Text(s) => Some(s),
            _ => None,
        }
    }

    /// 構造化データ参照を取得（Structured の場合のみ）
    pub fn structured(&self) -> Option<&serde_json::Value> {
        match self {
            Self::Structured(v) => Some(v),
            _ => None,
        }
    }
}

// ============================================================================
// ActionResult
// ============================================================================

/// Action 実行結果
#[derive(Debug, Clone)]
pub struct ActionResult {
    pub success: bool,
    pub output: Option<ActionOutput>,
    pub duration: Duration,
    pub error: Option<String>,
}

impl ActionResult {
    /// テキスト出力で成功
    pub fn success_text(output: impl Into<String>, duration: Duration) -> Self {
        Self {
            success: true,
            output: Some(ActionOutput::Text(output.into())),
            duration,
            error: None,
        }
    }

    /// 構造化データ出力で成功
    pub fn success_structured(output: serde_json::Value, duration: Duration) -> Self {
        Self {
            success: true,
            output: Some(ActionOutput::Structured(output)),
            duration,
            error: None,
        }
    }

    /// バイナリ出力で成功
    pub fn success_binary(output: Vec<u8>, duration: Duration) -> Self {
        Self {
            success: true,
            output: Some(ActionOutput::Binary(output)),
            duration,
            error: None,
        }
    }

    /// 後方互換: 文字列出力で成功（success_text のエイリアス）
    pub fn success(output: impl Into<String>, duration: Duration) -> Self {
        Self::success_text(output, duration)
    }

    /// 失敗
    pub fn failure(error: String, duration: Duration) -> Self {
        Self {
            success: false,
            output: None,
            duration,
            error: Some(error),
        }
    }
}

// ============================================================================
// ActionDef - Action 定義
// ============================================================================

/// パラメータ定義
#[derive(Debug, Clone)]
pub struct ParamDef {
    /// パラメータ名
    pub name: String,
    /// 説明
    pub description: String,
    /// 必須かどうか
    pub required: bool,
}

impl ParamDef {
    pub fn required(name: impl Into<String>, description: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            description: description.into(),
            required: true,
        }
    }

    pub fn optional(name: impl Into<String>, description: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            description: description.into(),
            required: false,
        }
    }
}

/// パラメータバリアント定義
///
/// ExplorationSpace がアクションの後続ノードを展開する際、
/// 指定されたパラメータ値のバリエーションを自動生成する。
#[derive(Debug, Clone)]
pub struct ParamVariants {
    /// パラメータのキー名（例: "target", "direction"）
    pub key: String,
    /// 取り得る値のリスト（例: ["north", "south", "east", "west"]）
    pub values: Vec<String>,
}

impl ParamVariants {
    /// 新しい ParamVariants を作成
    pub fn new(key: impl Into<String>, values: Vec<String>) -> Self {
        Self {
            key: key.into(),
            values,
        }
    }
}

/// Action 定義
#[derive(Debug, Clone)]
pub struct ActionDef {
    /// Action 名
    pub name: String,
    /// 説明（LLM プロンプト用）
    pub description: String,
    /// カテゴリ（探索空間への影響）
    pub category: ActionCategory,
    /// 所属 Group
    pub groups: Vec<String>,
    /// パラメータ定義
    pub params: Vec<ParamDef>,
    /// 出力例（LLM プロンプト用 JSON 形式）
    pub example: Option<String>,
    /// パラメータバリアント（ExplorationSpace で自動展開）
    ///
    /// 例: Move アクションで direction に対して ["north", "south", "east", "west"] を指定すると、
    /// ExplorationSpace が後続ノード展開時に 4 つのバリアントを生成する。
    ///
    /// - `param_key`: パラメータ名（例: "target", "direction"）
    /// - `variants`: 取り得る値のリスト
    pub param_variants: Option<ParamVariants>,
}

impl ActionDef {
    pub fn new(name: impl Into<String>, description: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            description: description.into(),
            category: ActionCategory::default(),
            groups: Vec::new(),
            params: Vec::new(),
            example: None,
            param_variants: None,
        }
    }

    /// パラメータバリアントを設定
    ///
    /// ExplorationSpace が後続ノード展開時に、指定されたバリアントを自動生成する。
    ///
    /// # Example
    ///
    /// ```ignore
    /// ActionDef::new("Move", "Move to adjacent cell")
    ///     .param_variants("target", vec!["north", "south", "east", "west"])
    /// ```
    pub fn param_variants(
        mut self,
        key: impl Into<String>,
        values: impl IntoIterator<Item = impl Into<String>>,
    ) -> Self {
        self.param_variants = Some(ParamVariants::new(
            key,
            values.into_iter().map(|v| v.into()).collect(),
        ));
        self
    }

    /// カテゴリを設定
    pub fn category(mut self, category: ActionCategory) -> Self {
        self.category = category;
        self
    }

    /// NodeExpand カテゴリに設定（新しい探索対象を発見する Action）
    pub fn node_expand(mut self) -> Self {
        self.category = ActionCategory::NodeExpand;
        self
    }

    /// NodeStateChange カテゴリに設定（既存 Node の状態を遷移させる Action）
    pub fn node_state_change(mut self) -> Self {
        self.category = ActionCategory::NodeStateChange;
        self
    }

    /// Group を設定
    pub fn groups<I, S>(mut self, groups: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        self.groups = groups.into_iter().map(|s| s.into()).collect();
        self
    }

    /// Group を追加
    pub fn group(mut self, group: impl Into<String>) -> Self {
        self.groups.push(group.into());
        self
    }

    /// パラメータを追加
    pub fn param(mut self, param: ParamDef) -> Self {
        self.params.push(param);
        self
    }

    /// 必須パラメータを追加
    pub fn required_param(self, name: impl Into<String>, description: impl Into<String>) -> Self {
        self.param(ParamDef::required(name, description))
    }

    /// オプションパラメータを追加
    pub fn optional_param(self, name: impl Into<String>, description: impl Into<String>) -> Self {
        self.param(ParamDef::optional(name, description))
    }

    /// 出力例を設定（LLM プロンプト用 JSON 形式）
    pub fn example(mut self, example: impl Into<String>) -> Self {
        self.example = Some(example.into());
        self
    }

    /// 指定した Group に所属しているか
    pub fn has_group(&self, group: &str) -> bool {
        self.groups.iter().any(|g| g == group)
    }

    /// 指定した Group のいずれかに所属しているか
    pub fn has_any_group(&self, groups: &[&str]) -> bool {
        groups.iter().any(|g| self.has_group(g))
    }
}

// ============================================================================
// ActionGroup - Action グループ（フィルタリング用）
// ============================================================================

/// Action グループ定義
///
/// include/exclude で Action をフィルタリングする。
/// include が空の場合は全 Action が対象。
#[derive(Debug, Clone, Default)]
pub struct ActionGroup {
    /// グループ名
    pub name: String,
    /// 含める Group（これらの Group を持つ Action を含む）
    pub include_groups: Vec<String>,
    /// 除外する Group（これらの Group を持つ Action を除外）
    pub exclude_groups: Vec<String>,
}

impl ActionGroup {
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            include_groups: Vec::new(),
            exclude_groups: Vec::new(),
        }
    }

    /// 含める Group を設定
    pub fn include<I, S>(mut self, groups: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        self.include_groups = groups.into_iter().map(|s| s.into()).collect();
        self
    }

    /// 除外する Group を設定
    pub fn exclude<I, S>(mut self, groups: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        self.exclude_groups = groups.into_iter().map(|s| s.into()).collect();
        self
    }

    /// ActionDef がこの Group にマッチするか判定
    pub fn matches(&self, action: &ActionDef) -> bool {
        // exclude チェック（1つでも該当すれば除外）
        if self.exclude_groups.iter().any(|g| action.has_group(g)) {
            return false;
        }

        // include が空なら全て含む
        if self.include_groups.is_empty() {
            return true;
        }

        // include チェック（1つでも該当すれば含む）
        self.include_groups.iter().any(|g| action.has_group(g))
    }
}

// ============================================================================
// ActionsConfig - Actions 統一管理
// ============================================================================

/// Actions 統一管理
///
/// Orchestrator 内で使用される Action を Protocol として統一管理する。
/// Extensions に登録して Manager/Worker から参照する。
#[derive(Debug, Clone, Default)]
pub struct ActionsConfig {
    /// Action 定義
    actions: HashMap<String, ActionDef>,
    /// Group 定義
    groups: HashMap<String, ActionGroup>,
}

impl ActionsConfig {
    pub fn new() -> Self {
        Self::default()
    }

    /// Action を追加
    pub fn action(mut self, name: impl Into<String>, def: ActionDef) -> Self {
        let name = name.into();
        let mut def = def;
        def.name = name.clone();
        self.actions.insert(name, def);
        self
    }

    /// Action を追加（mutable）
    pub fn add_action(&mut self, name: impl Into<String>, def: ActionDef) {
        let name = name.into();
        let mut def = def;
        def.name = name.clone();
        self.actions.insert(name, def);
    }

    /// Group を追加
    pub fn group(mut self, name: impl Into<String>, group: ActionGroup) -> Self {
        let name = name.into();
        let mut group = group;
        group.name = name.clone();
        self.groups.insert(name, group);
        self
    }

    /// Group を追加（mutable）
    pub fn add_group(&mut self, name: impl Into<String>, group: ActionGroup) {
        let name = name.into();
        let mut group = group;
        group.name = name.clone();
        self.groups.insert(name, group);
    }

    // ========================================================================
    // Query API
    // ========================================================================

    /// 全 Action 名を取得
    pub fn all_action_names(&self) -> Vec<String> {
        self.actions.keys().cloned().collect()
    }

    /// 全 Action 定義を取得
    pub fn all_actions(&self) -> impl Iterator<Item = &ActionDef> {
        self.actions.values()
    }

    /// Action 定義を取得
    pub fn get(&self, name: &str) -> Option<&ActionDef> {
        self.actions.get(name)
    }

    /// Group 定義を取得
    pub fn get_group(&self, name: &str) -> Option<&ActionGroup> {
        self.groups.get(name)
    }

    /// 指定 Group に所属する Action を取得
    pub fn by_group(&self, group_name: &str) -> Vec<&ActionDef> {
        if let Some(group) = self.groups.get(group_name) {
            self.actions.values().filter(|a| group.matches(a)).collect()
        } else {
            // Group 定義がない場合は、直接その group を持つ Action を返す
            self.actions
                .values()
                .filter(|a| a.has_group(group_name))
                .collect()
        }
    }

    /// 指定 Group の Action 名リストを取得（LLM candidates 用）
    pub fn candidates_for(&self, group_name: &str) -> Vec<String> {
        self.by_group(group_name)
            .into_iter()
            .map(|a| a.name.clone())
            .collect()
    }

    /// 複数 Group のいずれかに所属する Action を取得
    pub fn by_groups(&self, group_names: &[&str]) -> Vec<&ActionDef> {
        self.actions
            .values()
            .filter(|a| group_names.iter().any(|g| a.has_group(g)))
            .collect()
    }

    /// 複数 Group の Action 名リストを取得
    pub fn candidates_by_groups(&self, group_names: &[&str]) -> Vec<String> {
        self.by_groups(group_names)
            .into_iter()
            .map(|a| a.name.clone())
            .collect()
    }

    /// NodeExpand カテゴリのアクション名を取得
    ///
    /// 探索系アクション（新しい探索対象を発見する）のみを返す。
    /// 初期展開時に使用する。
    pub fn node_expand_actions(&self) -> Vec<String> {
        self.actions
            .values()
            .filter(|a| a.category == ActionCategory::NodeExpand)
            .map(|a| a.name.clone())
            .collect()
    }

    /// NodeStateChange カテゴリのアクション名を取得
    pub fn node_state_change_actions(&self) -> Vec<String> {
        self.actions
            .values()
            .filter(|a| a.category == ActionCategory::NodeStateChange)
            .map(|a| a.name.clone())
            .collect()
    }

    /// 指定アクションのパラメータバリアントを取得
    ///
    /// ExplorationSpace がノード展開時にバリアントを生成するために使用。
    ///
    /// # Returns
    ///
    /// - `Some((key, values))`: パラメータバリアントが定義されている場合
    /// - `None`: 定義されていない場合
    pub fn param_variants(&self, action_name: &str) -> Option<(&str, &[String])> {
        self.actions
            .get(action_name)
            .and_then(|a| a.param_variants.as_ref())
            .map(|pv| (pv.key.as_str(), pv.values.as_slice()))
    }

    // ========================================================================
    // Action Builder
    // ========================================================================

    /// Action を構築
    ///
    /// DecisionResponse から Action を構築する際に使用。
    /// 登録されていない Action 名の場合は None を返す。
    pub fn build_action(
        &self,
        name: &str,
        target: Option<String>,
        args: HashMap<String, String>,
    ) -> Option<Action> {
        self.actions.get(name).map(|_def| Action {
            name: name.to_string(),
            params: ActionParams {
                target,
                args,
                data: Vec::new(),
            },
        })
    }

    /// Action を構築（登録されていなくても作成）
    ///
    /// バリデーションなしで Action を作成する。
    /// 動的な Action 名に対応する場合に使用。
    pub fn build_action_unchecked(
        &self,
        name: impl Into<String>,
        target: Option<String>,
        args: HashMap<String, String>,
    ) -> Action {
        Action {
            name: name.into(),
            params: ActionParams {
                target,
                args,
                data: Vec::new(),
            },
        }
    }

    // ========================================================================
    // Validation
    // ========================================================================

    /// Action をバリデート
    pub fn validate(&self, action: &Action) -> Result<(), ActionValidationError> {
        let def = self
            .actions
            .get(&action.name)
            .ok_or_else(|| ActionValidationError::UnknownAction(action.name.clone()))?;

        // 必須パラメータチェック
        for param in &def.params {
            if param.required && !action.params.args.contains_key(&param.name) {
                return Err(ActionValidationError::MissingParam(param.name.clone()));
            }
        }

        Ok(())
    }
}

/// Action バリデーションエラー
#[derive(Debug, Clone, thiserror::Error)]
pub enum ActionValidationError {
    #[error("Unknown action: {0}")]
    UnknownAction(String),

    #[error("Missing required parameter: {0}")]
    MissingParam(String),

    #[error("Invalid parameter value: {0}")]
    InvalidParam(String),
}

// ============================================================================
// Tests
// ============================================================================

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

    fn sample_config() -> ActionsConfig {
        ActionsConfig::new()
            .action(
                "read_file",
                ActionDef::new("read_file", "ファイルを読み込む")
                    .groups(["file_ops", "exploration"])
                    .required_param("path", "ファイルパス"),
            )
            .action(
                "grep",
                ActionDef::new("grep", "パターン検索")
                    .groups(["search", "exploration"])
                    .required_param("pattern", "検索パターン"),
            )
            .action(
                "write_file",
                ActionDef::new("write_file", "ファイルを書き込む")
                    .groups(["file_ops", "mutation"])
                    .required_param("path", "ファイルパス")
                    .required_param("content", "内容"),
            )
            .action(
                "escalate",
                ActionDef::new("escalate", "Manager に報告").groups(["control"]),
            )
            .group(
                "readonly",
                ActionGroup::new("readonly")
                    .include(["exploration", "search"])
                    .exclude(["mutation"]),
            )
            .group(
                "all",
                ActionGroup::new("all"), // include/exclude なし = 全部
            )
    }

    #[test]
    fn test_by_group_direct() {
        let cfg = sample_config();

        // 直接 group 名で取得
        let file_ops = cfg.by_group("file_ops");
        assert_eq!(file_ops.len(), 2);

        let exploration = cfg.by_group("exploration");
        assert_eq!(exploration.len(), 2);
    }

    #[test]
    fn test_by_group_defined() {
        let cfg = sample_config();

        // 定義された Group で取得
        let readonly = cfg.candidates_for("readonly");
        assert!(readonly.contains(&"read_file".to_string()));
        assert!(readonly.contains(&"grep".to_string()));
        assert!(!readonly.contains(&"write_file".to_string())); // mutation なので除外

        let all = cfg.candidates_for("all");
        assert_eq!(all.len(), 4);
    }

    #[test]
    fn test_build_action() {
        let cfg = sample_config();

        let action = cfg.build_action(
            "read_file",
            Some("/path/to/file".to_string()),
            HashMap::new(),
        );
        assert!(action.is_some());
        assert_eq!(action.unwrap().name, "read_file");

        let unknown = cfg.build_action("unknown", None, HashMap::new());
        assert!(unknown.is_none());
    }

    #[test]
    fn test_validate() {
        let cfg = sample_config();

        // 有効な Action
        let action = Action {
            name: "read_file".to_string(),
            params: ActionParams {
                target: None,
                args: [("path".to_string(), "/tmp/test".to_string())]
                    .into_iter()
                    .collect(),
                data: Vec::new(),
            },
        };
        assert!(cfg.validate(&action).is_ok());

        // 必須パラメータ不足
        let action_missing = Action {
            name: "read_file".to_string(),
            params: ActionParams::default(),
        };
        assert!(matches!(
            cfg.validate(&action_missing),
            Err(ActionValidationError::MissingParam(_))
        ));

        // 未知の Action
        let unknown = Action {
            name: "unknown".to_string(),
            params: ActionParams::default(),
        };
        assert!(matches!(
            cfg.validate(&unknown),
            Err(ActionValidationError::UnknownAction(_))
        ));
    }
}