theway-daemon 0.1.21

//! Tool ASSEMBLY layer — the application-layer half of the session tool set.
//!
//! All tool BODIES (harness-runtime tools AND local-execution tools) live HERE, in
//! the daemon (daemon-kernel-layers: the daemon is the single kernel; the engine
//! crate `theway_core` keeps only the `AgentTool` / `ToolExecutor` / `ExecutionEnv`
//! trait families and the agent runtime):
//!
//! - **Harness-runtime tools** (graph/DAG, subagents, skills, memory, MCP — formerly
//!   `theway_core::tools`) sit next to the local bodies: `assembly` / `subagent` /
//!   `dag_tools` / the skill family / `memory` / `mcp_adapter` / `exec_shell`.
//! - **Local-execution tool bodies** (bash / fs / git / grep / find / ls / outline /
//!   truncate) are environment-specific agent capabilities.
//! - **Web tool** (`web_fetch`) is an app-layer capability too (it needs external
//!   credentials/configuration).
//! - **Assembly**: [`local_tools`] / the subagent tool-set resolver / `session_tool_set`
//!   wire engine tools + local tools together, then append the server-side
//!   trigger/cron family.
//!
//! Subagent tool sets are injected into the engine (specs carry no tool
//! factory): [`subagent_tool_sets`] builds the ONE resolver both `subagent_tool` and the
//! DAG node launcher are constructed with — every spec gets the same uniform set (engine
//! tools minus `subagent`/`dag_*` plus local tools); behavior is prompt-defined.

use std::path::PathBuf;
use std::sync::Arc;

use async_trait::async_trait;
use serde_json::Value;
use theway_core::executor::ToolExecutor;
use theway_core::multiagent::graph::engine::DagEngine;
use theway_core::multiagent::graph::node_launcher;
use theway_core::multiagent::jobs::SubagentJobRegistry;
use theway_core::multiagent::types::ToolSetResolver;
use theway_core::{
    AgentTool, AgentToolError, AgentToolResult, AgentToolUpdate, PermissionClassification,
};
use theway_llm_provider::Tool;
use tokio_util::sync::CancellationToken;

use crate::runtime_storage::SessionRepository;
use crate::tools::skill::SkillHarnessCell;

// ── tool bodies (harness-runtime + app-layer) ───────────────────────────────
//
// Plain module declarations: `tests/tools.rs` pulls in only `triggers/tool_assembly.rs`
// by `#[path]`, so nothing here needs `#[path]` re-routing — a plain `pub mod bash;`
// resolves `src/tools/bash.rs` and lets `bash.rs`'s own `mod tests;` find
// `src/tools/bash/tests/` (a `#[path]`-included module would break that resolution).

// Harness-runtime tools (moved from theway-core, daemon-kernel-layers).
pub mod assembly;
pub mod dag_tools;
pub mod exec;
pub mod exec_shell;
pub mod install_skill;
pub mod mcp_adapter;
pub mod memory;
pub mod remove_skill;
pub mod session_graph;
pub mod set_skill_state;
pub mod skill;
pub mod skill_builder;
pub mod subagent;

// App-layer local-execution + web tools.
pub mod bash;
pub mod edit;
pub mod find;
pub mod git;
pub mod grep;
pub mod ls;
pub mod outline;
pub mod read;
pub mod session_tool_result;
pub mod truncate;
pub mod web_fetch;
pub mod write;

// Trigger/cron model-facing constructors live in `triggers::tool_assembly` (kept
// out of this file so `tests/tools.rs` can `#[path]`-include just those).
pub use crate::triggers::tool_assembly::{
    list_cron_jobs_tool, list_triggers_tool, new_cron_job_tool, new_trigger_tool,
    remove_cron_job_tool, remove_trigger_tool, set_cron_job_state_tool, set_trigger_state_tool,
};

/// Tool names that bypass the [`ToolExecutor`] seam and touch the host OS directly:
/// `bash` spawns `sh -c` process groups (setsid/killpg), the `exec_shell` family owns
/// `tokio::process` children, and `ls` / `grep` / `find` walk the local filesystem
/// with `tokio::fs` / `ignore`. They are registered ONLY in `local` execution mode.
/// In sandbox mode (issue #123: selected at runtime via `[executor] kind` in
/// config.toml) they are omitted from the tool set (fail closed, issue #64) —
/// the [`crate::executor::sandbox::SandboxExecutor`] seam covers only the
/// executor-backed tools, so these bodies would otherwise keep acting straight on the
/// host even in sandbox mode.
pub const LOCAL_ONLY_TOOL_NAMES: &[&str] = &[
    "bash",
    "exec",
    "get_output",
    "kill_shell",
    "write_to_process",
    "ls",
    "grep",
    "find",
];

/// Scopes a direct-OS tool to an owning cwd unless the caller supplies one.
pub struct CwdScopedTool {
    inner: Arc<dyn AgentTool>,
    cwd: PathBuf,
}

impl CwdScopedTool {
    pub fn new(inner: Arc<dyn AgentTool>, cwd: PathBuf) -> Self {
        Self { inner, cwd }
    }

    fn scope_args(&self, mut args: Value) -> Value {
        match self.inner.definition().name.as_str() {
            "bash" | "exec" | "ls" | "grep" | "find" if args.get("cwd").is_none() => {
                if let Some(obj) = args.as_object_mut() {
                    obj.insert("cwd".into(), self.cwd.to_string_lossy().into_owned().into());
                }
            }
            _ => {}
        }
        args
    }
}

#[async_trait]
impl AgentTool for CwdScopedTool {
    fn definition(&self) -> &Tool {
        self.inner.definition()
    }

    fn label(&self) -> &str {
        self.inner.label()
    }

    fn execution_mode(&self) -> Option<theway_core::ToolExecutionMode> {
        self.inner.execution_mode()
    }

    fn prepare_arguments(&self, args: Value) -> Value {
        self.inner.prepare_arguments(self.scope_args(args))
    }

    fn permission_classification(&self, prepared_args: &Value) -> PermissionClassification {
        self.inner.permission_classification(prepared_args)
    }

    async fn execute(
        &self,
        tool_call_id: &str,
        params: Value,
        cancel: CancellationToken,
        on_update: Option<AgentToolUpdate>,
    ) -> Result<AgentToolResult, AgentToolError> {
        self.inner
            .execute(tool_call_id, self.scope_args(params), cancel, on_update)
            .await
    }
}

/// Compatibility wrapper that uses the process cwd as the owning cwd.
pub fn local_tools(executor: Arc<dyn ToolExecutor>) -> Vec<Arc<dyn AgentTool>> {
    local_tools_for_cwd(executor, std::env::current_dir().unwrap_or_default())
}

/// Local-execution tool set (the app-layer half of the session tool set): shell / fs /
/// git / grep / web — everything that depends on the execution environment. No engine
/// tools here (DAG / subagent / skills / memory come from the kernel's own assembly,
/// [`crate::tools::assembly`]); no duplicate-memory risk.
///
/// Executor binding (sdk-split-local-sandbox node 8): file-content and process tools
/// (read / write / edit / outline / git) dispatch their effects through the injected
/// [`ToolExecutor`] — the local executor for local editing mode; a sandbox
/// executor swaps the execution environment without touching tool definitions. The
/// remaining local tools are not yet wired through the executor: `bash` keeps its
/// process-group-kill + cancel semantics (the executor's `run_command` kills only the
/// direct child), and `ls` / `grep` / `find` / the `exec_shell` family use richer
/// directory/walk surfaces than the executor trait's first cut exposes.
pub fn local_tools_for_cwd(
    executor: Arc<dyn ToolExecutor>,
    cwd: PathBuf,
) -> Vec<Arc<dyn AgentTool>> {
    local_tools_for_cwd_with_tgrep(executor, cwd, None)
}

/// [`local_tools_for_cwd`] with the daemon-wide tgrep registry attached to the
/// grep tool (issue #121). `None` keeps the grep tool on its in-process walker.
pub fn local_tools_for_cwd_with_tgrep(
    executor: Arc<dyn ToolExecutor>,
    cwd: PathBuf,
    tgrep: Option<crate::tgrep_server::TgrepServerRegistry>,
) -> Vec<Arc<dyn AgentTool>> {
    vec![
        Arc::new(read::ReadTool::new(executor.clone())),
        Arc::new(write::WriteTool::new(executor.clone())),
        Arc::new(edit::EditTool::new(executor.clone())),
        Arc::new(CwdScopedTool::new(Arc::new(bash::BashTool), cwd.clone())),
        Arc::new(CwdScopedTool::new(
            Arc::new(exec_shell::ExecTool),
            cwd.clone(),
        )),
        Arc::new(exec_shell::GetOutputTool),
        Arc::new(exec_shell::KillShellTool),
        Arc::new(exec_shell::WriteToProcessTool),
        Arc::new(CwdScopedTool::new(Arc::new(ls::LsTool), cwd.clone())),
        Arc::new(CwdScopedTool::new(
            Arc::new(grep::GrepTool::new(tgrep, cwd.clone())),
            cwd.clone(),
        )),
        Arc::new(CwdScopedTool::new(Arc::new(find::FindTool), cwd)),
        Arc::new(outline::OutlineTool::new(executor.clone())),
        Arc::new(git::GitTool::new(executor)),
        Arc::new(web_fetch::WebFetchTool),
    ]
}

/// Sandbox tool set: only the executor-backed tools and the network-only web
/// tool are registered (issue #64, fail closed). The omitted direct-OS tools
/// are named explicitly in a `tracing::warn` so the degraded tool set is never
/// silent.
pub fn sandbox_tools_for_cwd(executor: Arc<dyn ToolExecutor>) -> Vec<Arc<dyn AgentTool>> {
    tracing::warn!(
        omitted = ?LOCAL_ONLY_TOOL_NAMES,
        "sandbox execution mode: local-only tools bypass the ToolExecutor seam and touch \
         the host FS/process table directly, so they are NOT registered (fail closed); \
         executor-backed tools (read/write/edit/outline/git) and the network-only
         web_fetch tool remain"
    );
    vec![
        Arc::new(read::ReadTool::new(executor.clone())),
        Arc::new(write::WriteTool::new(executor.clone())),
        Arc::new(edit::EditTool::new(executor.clone())),
        Arc::new(outline::OutlineTool::new(executor.clone())),
        Arc::new(git::GitTool::new(executor)),
        Arc::new(web_fetch::WebFetchTool),
    ]
}

/// Runtime execution-environment tool set (issue #123): `local` registers the
/// full local tool set (including direct-OS tools), `sandbox` registers only
/// the executor-backed tools plus `web_fetch`. The daemon's session/subagent
/// assembly calls this with the `[executor] kind` selected at startup; the
/// older [`local_tools_for_cwd_with_tgrep`] entry points stay local for
/// compatibility with tests and embedders.
pub fn tools_for_cwd_with_tgrep(
    executor: Arc<dyn ToolExecutor>,
    cwd: PathBuf,
    tgrep: Option<crate::tgrep_server::TgrepServerRegistry>,
    kind: theway_core::executor::ExecutorKind,
) -> Vec<Arc<dyn AgentTool>> {
    match kind {
        theway_core::executor::ExecutorKind::Local => {
            local_tools_for_cwd_with_tgrep(executor, cwd, tgrep)
        }
        theway_core::executor::ExecutorKind::Sandbox => sandbox_tools_for_cwd(executor),
    }
}

/// Build the `Subagent` tool. Separate from `local_tools` because the tool needs the model handle to
/// spawn its inner harness; the caller wires it in at construction time. `session_id`
/// (session-resource-model) stamps the owning session on every spawned job — each harness
/// build gets its own SubagentTool stamped with that harness's session.
///
/// The subagent tool set comes from [`subagent_tool_sets`] — the SAME resolver the DAG
/// node launcher gets (one uniform set per spec: engine tools minus subagent/dag_* plus
/// local tools). The main agent picks the spec (explorer / planner / executor-coder /
/// checker / general) and defines in the prompt what the subagent may do.
pub fn subagent_tool(
    model: impl Into<Option<theway_llm_provider::Model>>,
    stream_fn: Option<theway_core::StreamFn>,
    registry: SubagentJobRegistry,
    memory_dir: PathBuf,
    base_dir: PathBuf,
    skill_harness_cell: SkillHarnessCell,
    session_id: Option<String>,
    executor: Arc<dyn ToolExecutor>,
) -> Arc<dyn AgentTool> {
    Arc::new(
        subagent::SubagentTool::new(
            model,
            stream_fn,
            subagent_tool_sets(memory_dir, base_dir, skill_harness_cell, executor),
            crate::agent_specs::launch_resolver(),
            crate::agent_specs::spec_names(),
            registry,
        )
        .with_session_id(session_id),
    )
}

/// Build the app-layer tool-set resolver injected into the subagent tool and the DAG
/// node launcher. ONE uniform set for every spec: engine tools minus the two
/// orchestration tools (`subagent` / `dag_*`) plus local tools — assembled kernel-side,
/// [`crate::tools::assembly::subagent_tools`]. Per-spec tool differences are gone;
/// behavior is defined by the spec's system prompt and the parent's task prompt.
/// `base_dir` is the theway base dir (issue #66: `DaemonPaths::base`) for the skill
/// family's host paths.
pub fn subagent_tool_sets(
    memory_dir: PathBuf,
    base_dir: PathBuf,
    skill_harness_cell: SkillHarnessCell,
    executor: Arc<dyn ToolExecutor>,
) -> ToolSetResolver {
    subagent_tool_sets_for_cwd(
        memory_dir,
        base_dir,
        skill_harness_cell,
        executor,
        std::env::current_dir().unwrap_or_default(),
    )
}

pub fn subagent_tool_sets_for_cwd(
    memory_dir: PathBuf,
    base_dir: PathBuf,
    skill_harness_cell: SkillHarnessCell,
    executor: Arc<dyn ToolExecutor>,
    cwd: PathBuf,
) -> ToolSetResolver {
    subagent_tool_sets_for_cwd_with_tgrep(
        memory_dir,
        base_dir,
        skill_harness_cell,
        executor,
        cwd,
        None,
    )
}

/// [`subagent_tool_sets_for_cwd`] with the daemon-wide tgrep registry attached.
#[allow(clippy::too_many_arguments)]
pub fn subagent_tool_sets_for_cwd_with_tgrep(
    memory_dir: PathBuf,
    base_dir: PathBuf,
    skill_harness_cell: SkillHarnessCell,
    executor: Arc<dyn ToolExecutor>,
    cwd: PathBuf,
    tgrep: Option<crate::tgrep_server::TgrepServerRegistry>,
) -> ToolSetResolver {
    subagent_tool_sets_for_cwd_with_tgrep_and_kind(
        memory_dir,
        base_dir,
        skill_harness_cell,
        executor,
        cwd,
        tgrep,
        theway_core::executor::ExecutorKind::Local,
    )
}

/// [`subagent_tool_sets_for_cwd_with_tgrep`] with the runtime-selected execution
/// environment (issue #123). Sandbox mode swaps the app-layer tools for the
/// executor-backed set and drops the direct-FS engine tools.
#[allow(clippy::too_many_arguments)]
pub fn subagent_tool_sets_for_cwd_with_tgrep_and_kind(
    memory_dir: PathBuf,
    base_dir: PathBuf,
    skill_harness_cell: SkillHarnessCell,
    executor: Arc<dyn ToolExecutor>,
    cwd: PathBuf,
    tgrep: Option<crate::tgrep_server::TgrepServerRegistry>,
    kind: theway_core::executor::ExecutorKind,
) -> ToolSetResolver {
    assembly::subagent_tools_for_kind(
        &memory_dir,
        &base_dir,
        &skill_harness_cell,
        // The kernel-side local-tools factory closes over the daemon's executor and cwd,
        // so every subagent / DAG-node tool set dispatches through the same execution
        // environment and path-scoped direct-OS tools.
        Arc::new(move || {
            tools_for_cwd_with_tgrep(executor.clone(), cwd.clone(), tgrep.clone(), kind)
        }),
        kind,
    )
}

/// Build a DAG node launcher wired to `engine`, with the app-layer tool-set resolver.
/// `base_dir` is the theway base dir (issue #66: `DaemonPaths::base`) for the skill
/// family's host paths.
pub fn node_launcher(
    engine: Arc<DagEngine>,
    model: impl Into<Option<theway_llm_provider::Model>>,
    stream_fn: Option<theway_core::StreamFn>,
    cwd: PathBuf,
    registry: SubagentJobRegistry,
    memory_dir: PathBuf,
    base_dir: PathBuf,
    skill_harness_cell: SkillHarnessCell,
    executor: Arc<dyn ToolExecutor>,
    tgrep: Option<crate::tgrep_server::TgrepServerRegistry>,
) -> Arc<node_launcher::NodeLauncherImpl> {
    node_launcher_with_kind(
        engine,
        model,
        stream_fn,
        cwd,
        registry,
        memory_dir,
        base_dir,
        skill_harness_cell,
        executor,
        tgrep,
        theway_core::executor::ExecutorKind::Local,
    )
}

/// [`node_launcher`] with the runtime-selected execution environment (issue #123).
#[allow(clippy::too_many_arguments)]
pub fn node_launcher_with_kind(
    engine: Arc<DagEngine>,
    model: impl Into<Option<theway_llm_provider::Model>>,
    stream_fn: Option<theway_core::StreamFn>,
    cwd: PathBuf,
    registry: SubagentJobRegistry,
    memory_dir: PathBuf,
    base_dir: PathBuf,
    skill_harness_cell: SkillHarnessCell,
    executor: Arc<dyn ToolExecutor>,
    tgrep: Option<crate::tgrep_server::TgrepServerRegistry>,
    kind: theway_core::executor::ExecutorKind,
) -> Arc<node_launcher::NodeLauncherImpl> {
    node_launcher::node_launcher(
        engine,
        model.into(),
        stream_fn,
        cwd.clone(),
        registry,
        subagent_tool_sets_for_cwd_with_tgrep_and_kind(
            memory_dir,
            base_dir,
            skill_harness_cell,
            executor,
            cwd,
            tgrep,
            kind,
        ),
        crate::agent_specs::launch_resolver(),
    )
}

/// Build the per-session tool set (session-resource-model). One source of truth shared by
/// the CLI's initial harness build and the session factory ([`crate::session_ops::SessionFactory`]):
/// everything here is either session-stamped (`dag_*` / `subagent`) or must be rebuilt per
/// harness (the skill family wires a fresh harness cell per build). Local tools
/// ([`local_tools`]) + engine tools ([`crate::tools::assembly::engine_tools`]) +
/// the server-side trigger/cron family. Process-level tool groups (MCP tools) are the
/// caller's to add.
pub fn session_tool_set<'a>(
    memory_dir: &std::path::Path,
    base_dir: &std::path::Path,
    dag_engine: &Arc<DagEngine>,
    subagent_registry: &SubagentJobRegistry,
    model: impl Into<Option<&'a theway_llm_provider::Model>>,
    stream_fn: Option<&theway_core::StreamFn>,
    skill_harness_cell: &SkillHarnessCell,
    session_id: &str,
    executor: Arc<dyn ToolExecutor>,
    services: &crate::DaemonServices,
    repo: Arc<dyn SessionRepository>,
) -> Vec<Arc<dyn AgentTool>> {
    session_tool_set_for_cwd(
        memory_dir,
        base_dir,
        dag_engine,
        subagent_registry,
        model.into(),
        stream_fn,
        skill_harness_cell,
        session_id,
        executor,
        services,
        repo,
        std::env::current_dir().unwrap_or_default(),
    )
}

pub fn session_tool_set_for_cwd(
    memory_dir: &std::path::Path,
    base_dir: &std::path::Path,
    dag_engine: &Arc<DagEngine>,
    subagent_registry: &SubagentJobRegistry,
    model: Option<&theway_llm_provider::Model>,
    stream_fn: Option<&theway_core::StreamFn>,
    skill_harness_cell: &SkillHarnessCell,
    session_id: &str,
    executor: Arc<dyn ToolExecutor>,
    services: &crate::DaemonServices,
    repo: Arc<dyn SessionRepository>,
    cwd: PathBuf,
) -> Vec<Arc<dyn AgentTool>> {
    session_tool_set_for_cwd_with_kind(
        memory_dir,
        base_dir,
        dag_engine,
        subagent_registry,
        model,
        stream_fn,
        skill_harness_cell,
        session_id,
        executor,
        services,
        repo,
        cwd,
        theway_core::executor::ExecutorKind::Local,
    )
}

/// [`session_tool_set_for_cwd`] with the runtime-selected execution environment
/// (issue #123).
#[allow(clippy::too_many_arguments)]
pub fn session_tool_set_for_cwd_with_kind(
    memory_dir: &std::path::Path,
    base_dir: &std::path::Path,
    dag_engine: &Arc<DagEngine>,
    subagent_registry: &SubagentJobRegistry,
    model: Option<&theway_llm_provider::Model>,
    stream_fn: Option<&theway_core::StreamFn>,
    skill_harness_cell: &SkillHarnessCell,
    session_id: &str,
    executor: Arc<dyn ToolExecutor>,
    services: &crate::DaemonServices,
    repo: Arc<dyn SessionRepository>,
    cwd: PathBuf,
    kind: theway_core::executor::ExecutorKind,
) -> Vec<Arc<dyn AgentTool>> {
    let mut tools = tools_for_cwd_with_tgrep(
        executor.clone(),
        cwd.clone(),
        Some(services.tgrep.clone()),
        kind,
    );
    // Engine-owned tools (DAG / subagent / skills / memory), assembled kernel-side with the
    // same subagent tool-set resolver the DAG node launcher uses.
    tools.extend(assembly::engine_tools_for_kind(
        memory_dir,
        base_dir,
        dag_engine,
        subagent_registry,
        subagent_tool_sets_for_cwd_with_tgrep_and_kind(
            memory_dir.to_path_buf(),
            base_dir.to_path_buf(),
            skill_harness_cell.clone(),
            executor,
            cwd.clone(),
            Some(services.tgrep.clone()),
            kind,
        ),
        crate::agent_specs::launch_resolver(),
        crate::agent_specs::spec_names(),
        model,
        stream_fn,
        skill_harness_cell,
        session_id,
        services.reload.clone(),
        kind,
    ));
    // Session graph tools (main-agent only): list/read/status/wait/attach against
    // the Turso-backed session graph.
    let graph_path = theway_contract::config::sessions_dir_for_cwd(&cwd)
        .join(theway_storage::session_graph::SESSION_GRAPH_DB_FILE);
    tools.extend(session_graph::SessionGraphTools::create(
        repo.clone(),
        graph_path,
        cwd.clone(),
    ));
    // On-demand stored tool-result access (#50): the model can grep and page through
    // full results that were virtualized into placeholders in the LLM context.
    tools.extend(session_tool_result::SessionToolResultTools::create(
        repo.clone(),
        session_id.to_string(),
    ));
    // Trigger/cron family: harness-adjacent but implemented in this crate.
    tools.push(new_cron_job_tool(
        skill_harness_cell.clone(),
        services.cron.clone(),
    ));
    tools.push(list_cron_jobs_tool(services.cron.clone()));
    tools.push(remove_cron_job_tool(
        skill_harness_cell.clone(),
        services.cron.clone(),
    ));
    tools.push(set_cron_job_state_tool(
        skill_harness_cell.clone(),
        services.cron.clone(),
    ));
    tools.push(new_trigger_tool(services.dynamic_triggers.clone()));
    tools.push(list_triggers_tool(services.dynamic_triggers.clone()));
    tools.push(remove_trigger_tool(services.dynamic_triggers.clone()));
    tools.push(set_trigger_state_tool(services.dynamic_triggers.clone()));
    tools
}

#[cfg(test)]
// Test files live in `tests/tools/mod.rs` (mirror of src), pulled in by
// path so they keep unit-test semantics (private access). See docs/rust-test-files.md.
tests_bridge_macro::tests_bridge!("tools");