lingshu-tools 0.10.0

Tool registry, ToolHandler trait, and 50+ tool implementations
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# lingshu-tools

> **Why this crate?** LLM reasoning is only useful when it connects to the real world.  
> `lingshu-tools` is the action layer: a central `ToolRegistry`, a `ToolHandler` trait,  
> and 30+ ready-to-use tool implementations that let Lingshu read files, run commands,  
> browse the web, execute code, talk to MCP servers, and more — all with security checks  
> baked in at every boundary.

Part of [Lingshu](https://www.lingshu.com) — the Rust SuperAgent.

---

## Built-in tools (30+)

| Toolset | Tools |
|---------|-------|
| `file` | `file_read`, `file_write`, `file_patch`, `file_search` |
| `terminal` | `terminal` (local/SSH/Docker/Modal backends), `process` (background) |
| `web` | `web` (search + extract + crawl), `browser` (headless Chrome CDP) |
| `memory` | `memory` (MEMORY.md / USER.md read-write) |
| `skills` | `skills` (list/view/manage), `skills_hub` (remote registry), `skills_guard` (security scan) |
| `session` | `session_search` (FTS5 across history) |
| `delegation` | `delegate_task` (sub-agent), `mixture_of_agents` (MoA) |
| `code_execution` | `execute_code` (sandboxed runner) |
| `mcp` | `mcp_client` (stdio + HTTP Bearer, JSON-RPC 2.0) |
| `vision` | `vision` (multimodal image analysis) |
| `tts` | `tts` (text-to-speech) |
| `transcribe` | `transcribe` (audio → text) |
| `misc` | `todo`, `cron`, `clarify`, `checkpoint`, `advanced`, `pdf_to_markdown`, `homeassistant` |

## Add to your crate

```toml
[dependencies]
lingshu-tools = { path = "../lingshu-tools" }
```

## Implement a new tool

```rust
use async_trait::async_trait;
use serde::Deserialize;
use serde_json::json;
use lingshu_types::{ToolError, ToolSchema};
use lingshu_tools::registry::{ToolContext, ToolHandler};

pub struct EchoTool;

#[derive(Deserialize)]
struct EchoArgs { message: String }

#[async_trait]
impl ToolHandler for EchoTool {
    fn name(&self) -> &'static str { "echo" }
    fn toolset(&self) -> &'static str { "demo" }
    fn emoji(&self) -> &'static str { "📢" }

    fn schema(&self) -> ToolSchema {
        ToolSchema {
            name: "echo".into(),
            description: "Returns the message unchanged.".into(),
            parameters: json!({
                "type": "object",
                "properties": {
                    "message": { "type": "string", "description": "Text to echo" }
                },
                "required": ["message"]
            }),
            strict: None,
        }
    }

    async fn execute(&self, args: serde_json::Value, _ctx: &ToolContext) -> Result<String, ToolError> {
        let a: EchoArgs = serde_json::from_value(args)
            .map_err(|e| ToolError::InvalidArgs { tool: "echo".into(), message: e.to_string() })?;
        Ok(json!({"echo": a.message}).to_string())
    }
}

// Auto-register at startup
inventory::submit!(lingshu_tools::registry::RegisteredTool { handler: &EchoTool });
```

Add the module to `tools/mod.rs` and (optionally) to `CORE_TOOLS` in `toolsets.rs`.

## Security rules (enforced in every built-in tool)

- File paths → `lingshu_security::path_safety::validate_path()`
- Web URLs → `lingshu_security::ssrf::is_safe_url()`
- Shell args → `lingshu_security::command_scan::scan_command()`
- Skill installs → `skills_guard::scan_skill()` (23 threat patterns)

---

> Full docs, guides, and release notes → [lingshu.com](https://www.lingshu.com)