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);
                }
                // AI-SPEC §4b.1 / D-05: a model that keeps emitting
                // malformed args for the same tool name must not be
                // allowed to spin for the full MAX_TURNS budget — abort
                // with an apology as soon as any tool name crosses 2
                // consecutive validation failures, rather than continuing
                // to ask the model to try again.
                if ctx.should_abort() {
                    return Ok(
                        "I'm stopping here — the same tool call kept failing validation. \
                         Could you rephrase what you'd like me to do?"
                            .to_string(),
                    );
                }
                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 — AI-SPEC §4b.1), and D-07
/// (every destructive tool suspends for confirmation — 13-08 fills that
/// branch in; there are no reachable destructive tools yet, so it is
/// unreachable today even though the registry now has some).
///
/// `pub(crate)` (not private) so `assistant::tools`'s own test module can
/// exercise this exact choke point directly for S-05/S-07 — the point of
/// those tests is that the gate holds even when called the same way the
/// real loop calls it, not a reimplementation of the gate in the test.
pub(crate) 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),
        };
    };

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

    let args = match tool.validate(&call.arguments) {
        Ok(args) => {
            ctx.reset_validation_failures(&call.name);
            args
        }
        Err(e) => {
            ctx.note_validation_failure(&call.name);
            return ToolResult {
                call_id: call.id.clone(),
                is_error: true,
                content: format!("invalid arguments: {e}"),
            };
        }
    };

    // Business-rule validation (an allowlisted settings key, an installed
    // app id) runs BEFORE the destructive/confirm gate below — otherwise a
    // plainly-wrong request (an unlisted key, `claude_api_key`, an unknown
    // app id) would be swallowed by the destructive branch's generic
    // "not yet implemented" placeholder instead of being refused with the
    // real reason (13-05 Task 1's `<done>` criterion). This performs no
    // mutation itself — only a read-only id lookup for the app tools.
    if let Err(msg) = super::tools::validate_business_rules(&call.name, &args, ctx.handler.as_ref()).await {
        return ToolResult {
            call_id: call.id.clone(),
            is_error: true,
            content: msg,
        };
    }

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

    // D-06: dispatch is a per-tool, hand-written decision recorded in
    // `tools::dispatch` — never a generic pass-through of the model's tool
    // name onto the RPC surface.
    match super::tools::dispatch(&call.name, &args, ctx.handler.as_ref()).await {
        Ok(v) => ToolResult {
            call_id: call.id.clone(),
            is_error: false,
            content: v.to_string(),
        },
        Err(msg) => ToolResult {
            call_id: call.id.clone(),
            is_error: true,
            content: msg,
        },
    }
}

#[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::new(
            registry(),
            CallerScope::LocalOperator {
                session_id: "test-session".to_string(),
            },
            handler,
        )
    }

    /// D-16 defaults to closed, so tests that exercise a real tool call
    /// must explicitly open the category first — this is the test-side
    /// analog of an operator toggling a category on in neode-ui.
    async fn grant(handler: &Arc<RpcHandler>, category: PermissionCategory) {
        let mut g = crate::assistant::grants::Grants::load(handler.data_dir()).await;
        g.set(category, true);
        g.save(handler.data_dir()).await.expect("save grants");
    }

    #[tokio::test]
    async fn disk_status_tool_executes() {
        let (handler, _tmp) = test_rpc_handler().await;
        grant(&handler, PermissionCategory::System).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", None)
            .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)"
        );
    }
}