archy/core/archipelago/src/assistant/loop_.rs

//! The multi-turn tool-calling loop (D-01/D-02). No analog exists elsewhere
//! in this codebase — this is the first tool-calling agent loop ever
//! written here (confirmed by 13-RESEARCH.md/13-AI-SPEC.md); built directly
//! from `13-AI-SPEC.md` §3/§4's sketch.
//!
//! Concurrency discipline inherited from `mesh/listener/assist.rs`'s own
//! doc comment ("Spawned off the radio loop so it never blocks"): never
//! hold a shared lock across a `.await` that can block for human-response
//! time. `execute_tool` below holds no lock at all in this tracer — there
//! is nothing yet to hold one across (13-08's confirm gate is what
//! introduces that discipline requirement for real).

use anyhow::Result;

use super::backends::{Backend, BackendTurn};
use super::tools::{ChatMessage, Role, ToolCall, ToolResult};
use super::tools::ToolDef;
use super::ToolExecCtx;

/// Hard stop — a looping model must never spin unbounded (D-05).
pub const MAX_TURNS: usize = 8;

pub async fn run_loop(
    backend: &dyn Backend,
    system: &str,
    tools: &[ToolDef],
    mut history: Vec<ChatMessage>,
    ctx: &ToolExecCtx,
) -> Result<String> {
    for _ in 0..MAX_TURNS {
        match backend.send(system, tools, &history).await? {
            BackendTurn::Text(answer) => return Ok(answer),
            BackendTurn::ToolCalls(calls) => {
                history.push(ChatMessage {
                    role: Role::Assistant,
                    text: None,
                    tool_calls: calls.clone(),
                    tool_results: vec![],
                });
                let mut results = Vec::with_capacity(calls.len());
                for call in &calls {
                    results.push(execute_tool(call, ctx).await);
                }
                history.push(ChatMessage {
                    role: Role::Tool,
                    text: None,
                    tool_calls: vec![],
                    tool_results: results,
                });
            }
        }
    }
    anyhow::bail!("assistant loop exceeded MAX_TURNS without a final answer — stopping, not looping forever")
}

/// The single choke point every tool call passes through, regardless of
/// which backend produced it. Enforces, in order: D-06 (curated allowlist —
/// unknown names are refused, never silently ignored), D-16 (default-closed
/// category grants — re-checked here even though the system prompt already
/// omits ungranted tools; never trust that as the only enforcement layer),
/// schema validation (never coerce, never guess), and D-07 (every
/// destructive tool suspends for confirmation — 13-08 fills that branch in;
/// there are no destructive tools registered yet, so it is unreachable
/// today).
async fn execute_tool(call: &ToolCall, ctx: &ToolExecCtx) -> ToolResult {
    let Some(tool) = ctx.registry.get(&call.name) else {
        return ToolResult {
            call_id: call.id.clone(),
            is_error: true,
            content: format!("no such tool: {}", call.name),
        };
    };

    if !ctx.caller.granted_categories().contains(&tool.category) {
        return ToolResult {
            call_id: call.id.clone(),
            is_error: true,
            content: "not permitted — this category is not granted".to_string(),
        };
    }

    if let Err(e) = tool.validate(&call.arguments) {
        return ToolResult {
            call_id: call.id.clone(),
            is_error: true,
            content: format!("invalid arguments: {e}"),
        };
    }

    if tool.destructive {
        return ToolResult {
            call_id: call.id.clone(),
            is_error: true,
            content: "destructive tool execution is not yet implemented".to_string(),
        };
    }

    match call.name.as_str() {
        // Dispatches to the SAME RpcHandler method every other authenticated
        // caller uses (no AI-only backdoor) — see `assistant_dispatch_tool`
        // in `api/rpc/assistant_chat.rs` for why this bridge exists.
        "system_disk_status" => match ctx
            .handler
            .assistant_dispatch_tool("system.disk-status")
            .await
        {
            Ok(v) => ToolResult {
                call_id: call.id.clone(),
                is_error: false,
                content: v.to_string(),
            },
            Err(e) => ToolResult {
                call_id: call.id.clone(),
                is_error: true,
                content: format!("tool execution failed: {e}"),
            },
        },
        other => ToolResult {
            call_id: call.id.clone(),
            is_error: true,
            content: format!("no execution wired for tool: {other}"),
        },
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::assistant::backends::scripted::ScriptedBackend;
    use crate::assistant::tools::{registry, system_disk_status_tool};
    use crate::assistant::{CallerScope, PermissionCategory};
    use crate::api::rpc::RpcHandler;
    use serde_json::json;
    use std::sync::Arc;

    /// A minimal but real `RpcHandler` for tests: a fresh temp `data_dir`
    /// (no `/var/lib/archipelago` writes), no orchestrator (container RPCs
    /// aren't exercised here), matching the doc comment on `orchestrator`
    /// that this is exactly why the field is `Option`.
    async fn test_rpc_handler() -> (Arc<RpcHandler>, tempfile::TempDir) {
        let tmp = tempfile::tempdir().expect("tempdir");
        let mut config = crate::config::Config::default();
        config.data_dir = tmp.path().to_path_buf();
        let state_manager = Arc::new(crate::state::StateManager::new());
        let metrics_store = Arc::new(crate::monitoring::MetricsStore::new());
        let session_store =
            crate::session::SessionStore::new_for_tests(tmp.path().join("sessions.json"));
        let handler = RpcHandler::new(
            config,
            state_manager,
            metrics_store,
            session_store,
            None,
            None,
        )
        .await
        .expect("RpcHandler::new");
        (Arc::new(handler), tmp)
    }

    fn local_operator_ctx(handler: Arc<RpcHandler>) -> ToolExecCtx {
        ToolExecCtx {
            registry: registry(),
            caller: CallerScope::LocalOperator {
                session_id: "test-session".to_string(),
            },
            handler,
        }
    }

    #[tokio::test]
    async fn disk_status_tool_executes() {
        let (handler, _tmp) = test_rpc_handler().await;

        // The real figures the tool path returns must match what the SAME
        // handler returns when dispatched directly — proving `execute_tool`
        // is not a parallel, AI-only code path.
        let direct = handler
            .assistant_dispatch_tool("system.disk-status")
            .await
            .expect("direct dispatch");

        let ctx = local_operator_ctx(handler.clone());
        let call = ToolCall {
            id: "call-1".to_string(),
            name: "system_disk_status".to_string(),
            arguments: json!({}),
        };
        let result = execute_tool(&call, &ctx).await;
        assert!(!result.is_error, "tool call errored: {}", result.content);
        assert_eq!(result.content, direct.to_string());
        assert!(result.content.contains("total_bytes"));

        // Exercise the whole loop: a ScriptedBackend that names the tool,
        // then answers — proving the real figures reached the final answer
        // path (the answer itself is the second scripted turn, matching
        // AI-SPEC's run_loop shape; the tool result that fed into it is
        // asserted above).
        let backend = ScriptedBackend::new(vec![
            BackendTurn::ToolCalls(vec![call.clone()]),
            BackendTurn::Text("Disk space report generated.".to_string()),
        ]);
        let tools_list = vec![system_disk_status_tool()];
        let answer = run_loop(&backend, "system prompt", &tools_list, vec![], &ctx)
            .await
            .expect("run_loop");
        assert_eq!(answer, "Disk space report generated.");
    }

    #[tokio::test]
    async fn unknown_tool_is_refused_not_ignored() {
        let (handler, _tmp) = test_rpc_handler().await;
        let ctx = local_operator_ctx(handler);
        let call = ToolCall {
            id: "call-1".to_string(),
            name: "delete_everything".to_string(),
            arguments: json!({}),
        };
        let result = execute_tool(&call, &ctx).await;
        assert!(result.is_error);
        assert!(result.content.contains("no such tool"), "{}", result.content);
    }

    /// Phase-10 hard constraint: `assistant.*` must never be reachable
    /// unauthenticated. Asserted directly against the live list, not
    /// assumed.
    #[test]
    fn assistant_methods_require_session() {
        let has_assistant_method = crate::api::rpc::UNAUTHENTICATED_METHODS
            .iter()
            .any(|m| m.starts_with("assistant."));
        assert!(
            !has_assistant_method,
            "assistant.* must never be added to UNAUTHENTICATED_METHODS (Phase-10 hard constraint)"
        );
    }
}