clawft_kernel/wasm_runner/
catalog.rs

1//! Built-in tool catalog: 27+ kernel tool specifications.
2
3use super::types::*;
4use crate::governance::EffectVector;
5
6/// Return the complete catalog of 27 built-in kernel tools.
7pub fn builtin_tool_catalog() -> Vec<BuiltinToolSpec> {
8    let mut catalog = Vec::with_capacity(29);
9
10    // --- Filesystem tools (10) ---
11    catalog.push(BuiltinToolSpec {
12        name: "fs.read_file".into(),
13        category: ToolCategory::Filesystem,
14        description: "Read file contents with optional offset/limit".into(),
15        parameters: serde_json::json!({
16            "type": "object",
17            "properties": {
18                "path": {"type": "string", "description": "File path to read"},
19                "offset": {"type": "integer", "description": "Byte offset to start reading"},
20                "limit": {"type": "integer", "description": "Maximum bytes to read"}
21            },
22            "required": ["path"]
23        }),
24        gate_action: "tool.fs.read".into(),
25        effect: EffectVector {
26            risk: 0.1,
27            ..Default::default()
28        },
29        native: true,
30    });
31    catalog.push(BuiltinToolSpec {
32        name: "fs.write_file".into(),
33        category: ToolCategory::Filesystem,
34        description: "Write content to a file".into(),
35        parameters: serde_json::json!({
36            "type": "object",
37            "properties": {
38                "path": {"type": "string"},
39                "content": {"type": "string"},
40                "append": {"type": "boolean", "default": false}
41            },
42            "required": ["path", "content"]
43        }),
44        gate_action: "tool.fs.write".into(),
45        effect: EffectVector {
46            risk: 0.4,
47            ..Default::default()
48        },
49        native: true,
50    });
51    catalog.push(BuiltinToolSpec {
52        name: "fs.read_dir".into(),
53        category: ToolCategory::Filesystem,
54        description: "List directory contents".into(),
55        parameters: serde_json::json!({
56            "type": "object",
57            "properties": {
58                "path": {"type": "string"}
59            },
60            "required": ["path"]
61        }),
62        gate_action: "tool.fs.read".into(),
63        effect: EffectVector {
64            risk: 0.1,
65            ..Default::default()
66        },
67        native: true,
68    });
69    catalog.push(BuiltinToolSpec {
70        name: "fs.create_dir".into(),
71        category: ToolCategory::Filesystem,
72        description: "Create a directory (recursive)".into(),
73        parameters: serde_json::json!({
74            "type": "object",
75            "properties": {
76                "path": {"type": "string"},
77                "recursive": {"type": "boolean", "default": true}
78            },
79            "required": ["path"]
80        }),
81        gate_action: "tool.fs.write".into(),
82        effect: EffectVector {
83            risk: 0.3,
84            ..Default::default()
85        },
86        native: true,
87    });
88    catalog.push(BuiltinToolSpec {
89        name: "fs.remove".into(),
90        category: ToolCategory::Filesystem,
91        description: "Remove a file or directory".into(),
92        parameters: serde_json::json!({
93            "type": "object",
94            "properties": {
95                "path": {"type": "string"},
96                "recursive": {"type": "boolean", "default": false}
97            },
98            "required": ["path"]
99        }),
100        gate_action: "tool.fs.delete".into(),
101        effect: EffectVector {
102            risk: 0.7,
103            security: 0.3,
104            ..Default::default()
105        },
106        native: true,
107    });
108    catalog.push(BuiltinToolSpec {
109        name: "fs.copy".into(),
110        category: ToolCategory::Filesystem,
111        description: "Copy a file or directory".into(),
112        parameters: serde_json::json!({
113            "type": "object",
114            "properties": {
115                "src": {"type": "string"},
116                "dst": {"type": "string"}
117            },
118            "required": ["src", "dst"]
119        }),
120        gate_action: "tool.fs.write".into(),
121        effect: EffectVector {
122            risk: 0.3,
123            ..Default::default()
124        },
125        native: true,
126    });
127    catalog.push(BuiltinToolSpec {
128        name: "fs.move".into(),
129        category: ToolCategory::Filesystem,
130        description: "Move/rename a file or directory".into(),
131        parameters: serde_json::json!({
132            "type": "object",
133            "properties": {
134                "src": {"type": "string"},
135                "dst": {"type": "string"}
136            },
137            "required": ["src", "dst"]
138        }),
139        gate_action: "tool.fs.write".into(),
140        effect: EffectVector {
141            risk: 0.5,
142            ..Default::default()
143        },
144        native: true,
145    });
146    catalog.push(BuiltinToolSpec {
147        name: "fs.stat".into(),
148        category: ToolCategory::Filesystem,
149        description: "Get file/directory metadata".into(),
150        parameters: serde_json::json!({
151            "type": "object",
152            "properties": {
153                "path": {"type": "string"}
154            },
155            "required": ["path"]
156        }),
157        gate_action: "tool.fs.read".into(),
158        effect: EffectVector {
159            risk: 0.05,
160            ..Default::default()
161        },
162        native: true,
163    });
164    catalog.push(BuiltinToolSpec {
165        name: "fs.exists".into(),
166        category: ToolCategory::Filesystem,
167        description: "Check if a path exists".into(),
168        parameters: serde_json::json!({
169            "type": "object",
170            "properties": {
171                "path": {"type": "string"}
172            },
173            "required": ["path"]
174        }),
175        gate_action: "tool.fs.read".into(),
176        effect: EffectVector {
177            risk: 0.05,
178            ..Default::default()
179        },
180        native: true,
181    });
182    catalog.push(BuiltinToolSpec {
183        name: "fs.glob".into(),
184        category: ToolCategory::Filesystem,
185        description: "Find files matching a glob pattern".into(),
186        parameters: serde_json::json!({
187            "type": "object",
188            "properties": {
189                "pattern": {"type": "string"},
190                "base_dir": {"type": "string"}
191            },
192            "required": ["pattern"]
193        }),
194        gate_action: "tool.fs.read".into(),
195        effect: EffectVector {
196            risk: 0.1,
197            ..Default::default()
198        },
199        native: true,
200    });
201
202    // --- Agent tools (7) ---
203    catalog.push(BuiltinToolSpec {
204        name: "agent.spawn".into(),
205        category: ToolCategory::Agent,
206        description: "Spawn a new agent process".into(),
207        parameters: serde_json::json!({
208            "type": "object",
209            "properties": {
210                "agent_id": {"type": "string"},
211                "template": {"type": "string"},
212                "capabilities": {"type": "object"},
213                "backend": {"type": "string", "enum": ["native", "wasm", "container"]}
214            },
215            "required": ["agent_id"]
216        }),
217        gate_action: "tool.agent.spawn".into(),
218        effect: EffectVector {
219            risk: 0.5,
220            ..Default::default()
221        },
222        native: true,
223    });
224    catalog.push(BuiltinToolSpec {
225        name: "agent.stop".into(),
226        category: ToolCategory::Agent,
227        description: "Stop a running agent".into(),
228        parameters: serde_json::json!({
229            "type": "object",
230            "properties": {
231                "pid": {"type": "integer"},
232                "graceful": {"type": "boolean", "default": true}
233            },
234            "required": ["pid"]
235        }),
236        gate_action: "tool.agent.stop".into(),
237        effect: EffectVector {
238            risk: 0.4,
239            ..Default::default()
240        },
241        native: true,
242    });
243    catalog.push(BuiltinToolSpec {
244        name: "agent.list".into(),
245        category: ToolCategory::Agent,
246        description: "List all running agents".into(),
247        parameters: serde_json::json!({"type": "object", "properties": {}}),
248        gate_action: "tool.agent.read".into(),
249        effect: EffectVector {
250            risk: 0.05,
251            ..Default::default()
252        },
253        native: true,
254    });
255    catalog.push(BuiltinToolSpec {
256        name: "agent.inspect".into(),
257        category: ToolCategory::Agent,
258        description: "Inspect agent details".into(),
259        parameters: serde_json::json!({
260            "type": "object",
261            "properties": {
262                "pid": {"type": "integer"}
263            },
264            "required": ["pid"]
265        }),
266        gate_action: "tool.agent.read".into(),
267        effect: EffectVector {
268            risk: 0.1,
269            ..Default::default()
270        },
271        native: true,
272    });
273    catalog.push(BuiltinToolSpec {
274        name: "agent.send".into(),
275        category: ToolCategory::Agent,
276        description: "Send a message to an agent".into(),
277        parameters: serde_json::json!({
278            "type": "object",
279            "properties": {
280                "pid": {"type": "integer"},
281                "message": {"type": "object"}
282            },
283            "required": ["pid", "message"]
284        }),
285        gate_action: "tool.agent.ipc".into(),
286        effect: EffectVector {
287            risk: 0.2,
288            ..Default::default()
289        },
290        native: true,
291    });
292    catalog.push(BuiltinToolSpec {
293        name: "agent.suspend".into(),
294        category: ToolCategory::Agent,
295        description: "Suspend an agent".into(),
296        parameters: serde_json::json!({
297            "type": "object",
298            "properties": {
299                "pid": {"type": "integer"}
300            },
301            "required": ["pid"]
302        }),
303        gate_action: "tool.agent.suspend".into(),
304        effect: EffectVector {
305            risk: 0.3,
306            ..Default::default()
307        },
308        native: true,
309    });
310    catalog.push(BuiltinToolSpec {
311        name: "agent.resume".into(),
312        category: ToolCategory::Agent,
313        description: "Resume a suspended agent".into(),
314        parameters: serde_json::json!({
315            "type": "object",
316            "properties": {
317                "pid": {"type": "integer"}
318            },
319            "required": ["pid"]
320        }),
321        gate_action: "tool.agent.resume".into(),
322        effect: EffectVector {
323            risk: 0.2,
324            ..Default::default()
325        },
326        native: true,
327    });
328
329    // --- IPC tools (2) ---
330    catalog.push(BuiltinToolSpec {
331        name: "ipc.send".into(),
332        category: ToolCategory::Agent,
333        description: "Send a message to an agent or topic via kernel IPC".into(),
334        parameters: serde_json::json!({
335            "type": "object",
336            "properties": {
337                "target_pid": {"type": "integer", "description": "Target agent PID"},
338                "topic": {"type": "string", "description": "Topic name (alternative to target_pid)"},
339                "payload": {"type": "object", "description": "Message payload (JSON)"},
340                "text": {"type": "string", "description": "Plain text message (alternative to payload)"}
341            }
342        }),
343        gate_action: "tool.ipc.send".into(),
344        effect: EffectVector { risk: 0.2, ..Default::default() },
345        native: true,
346    });
347    catalog.push(BuiltinToolSpec {
348        name: "ipc.subscribe".into(),
349        category: ToolCategory::Agent,
350        description: "Subscribe to a topic for receiving messages".into(),
351        parameters: serde_json::json!({
352            "type": "object",
353            "properties": {
354                "topic": {"type": "string", "description": "Topic name to subscribe to"},
355                "pid": {"type": "integer", "description": "PID to subscribe (defaults to caller)"}
356            },
357            "required": ["topic"]
358        }),
359        gate_action: "tool.ipc.subscribe".into(),
360        effect: EffectVector {
361            risk: 0.1,
362            ..Default::default()
363        },
364        native: true,
365    });
366
367    // --- System tools (10) ---
368    catalog.push(BuiltinToolSpec {
369        name: "sys.service.list".into(),
370        category: ToolCategory::System,
371        description: "List registered services".into(),
372        parameters: serde_json::json!({"type": "object", "properties": {}}),
373        gate_action: "tool.sys.read".into(),
374        effect: EffectVector {
375            risk: 0.05,
376            ..Default::default()
377        },
378        native: true,
379    });
380    catalog.push(BuiltinToolSpec {
381        name: "sys.service.health".into(),
382        category: ToolCategory::System,
383        description: "Check service health".into(),
384        parameters: serde_json::json!({
385            "type": "object",
386            "properties": {
387                "name": {"type": "string"}
388            }
389        }),
390        gate_action: "tool.sys.read".into(),
391        effect: EffectVector {
392            risk: 0.05,
393            ..Default::default()
394        },
395        native: true,
396    });
397    catalog.push(BuiltinToolSpec {
398        name: "sys.chain.status".into(),
399        category: ToolCategory::System,
400        description: "Get chain status".into(),
401        parameters: serde_json::json!({"type": "object", "properties": {}}),
402        gate_action: "tool.sys.read".into(),
403        effect: EffectVector {
404            risk: 0.05,
405            ..Default::default()
406        },
407        native: true,
408    });
409    catalog.push(BuiltinToolSpec {
410        name: "sys.chain.query".into(),
411        category: ToolCategory::System,
412        description: "Query chain events".into(),
413        parameters: serde_json::json!({
414            "type": "object",
415            "properties": {
416                "count": {"type": "integer", "default": 20},
417                "source": {"type": "string"},
418                "kind": {"type": "string"}
419            }
420        }),
421        gate_action: "tool.sys.read".into(),
422        effect: EffectVector {
423            risk: 0.1,
424            ..Default::default()
425        },
426        native: true,
427    });
428    catalog.push(BuiltinToolSpec {
429        name: "sys.tree.read".into(),
430        category: ToolCategory::System,
431        description: "Read resource tree".into(),
432        parameters: serde_json::json!({"type": "object", "properties": {}}),
433        gate_action: "tool.sys.read".into(),
434        effect: EffectVector {
435            risk: 0.05,
436            ..Default::default()
437        },
438        native: true,
439    });
440    catalog.push(BuiltinToolSpec {
441        name: "sys.tree.inspect".into(),
442        category: ToolCategory::System,
443        description: "Inspect a resource tree node".into(),
444        parameters: serde_json::json!({
445            "type": "object",
446            "properties": {
447                "path": {"type": "string"}
448            },
449            "required": ["path"]
450        }),
451        gate_action: "tool.sys.read".into(),
452        effect: EffectVector {
453            risk: 0.1,
454            ..Default::default()
455        },
456        native: true,
457    });
458    catalog.push(BuiltinToolSpec {
459        name: "sys.env.get".into(),
460        category: ToolCategory::System,
461        description: "Get environment variable".into(),
462        parameters: serde_json::json!({
463            "type": "object",
464            "properties": {
465                "name": {"type": "string"}
466            },
467            "required": ["name"]
468        }),
469        gate_action: "tool.sys.env".into(),
470        effect: EffectVector {
471            risk: 0.2,
472            privacy: 0.3,
473            ..Default::default()
474        },
475        native: true,
476    });
477    catalog.push(BuiltinToolSpec {
478        name: "sys.cron.add".into(),
479        category: ToolCategory::System,
480        description: "Add a cron job".into(),
481        parameters: serde_json::json!({
482            "type": "object",
483            "properties": {
484                "name": {"type": "string"},
485                "interval_secs": {"type": "integer"},
486                "command": {"type": "string"},
487                "target_pid": {"type": "integer"}
488            },
489            "required": ["name", "interval_secs", "command"]
490        }),
491        gate_action: "tool.sys.cron".into(),
492        effect: EffectVector {
493            risk: 0.4,
494            ..Default::default()
495        },
496        native: true,
497    });
498    catalog.push(BuiltinToolSpec {
499        name: "sys.cron.list".into(),
500        category: ToolCategory::System,
501        description: "List cron jobs".into(),
502        parameters: serde_json::json!({"type": "object", "properties": {}}),
503        gate_action: "tool.sys.read".into(),
504        effect: EffectVector {
505            risk: 0.05,
506            ..Default::default()
507        },
508        native: true,
509    });
510    catalog.push(BuiltinToolSpec {
511        name: "sys.cron.remove".into(),
512        category: ToolCategory::System,
513        description: "Remove a cron job".into(),
514        parameters: serde_json::json!({
515            "type": "object",
516            "properties": {
517                "id": {"type": "string"}
518            },
519            "required": ["id"]
520        }),
521        gate_action: "tool.sys.cron".into(),
522        effect: EffectVector {
523            risk: 0.3,
524            ..Default::default()
525        },
526        native: true,
527    });
528
529    // --- ECC tools (7, behind `ecc` feature) ---
530    #[cfg(feature = "ecc")]
531    {
532        catalog.push(BuiltinToolSpec {
533            name: "ecc.embed".into(),
534            category: ToolCategory::Ecc,
535            description: "Insert vector into HNSW index".into(),
536            parameters: serde_json::json!({
537                "type": "object",
538                "properties": {
539                    "id": {"type": "string"},
540                    "embedding": {"type": "array", "items": {"type": "number"}},
541                    "metadata": {"type": "object"}
542                },
543                "required": ["id", "embedding"]
544            }),
545            gate_action: "ecc.embed".into(),
546            effect: EffectVector {
547                risk: 0.1,
548                ..Default::default()
549            },
550            native: true,
551        });
552        catalog.push(BuiltinToolSpec {
553            name: "ecc.search".into(),
554            category: ToolCategory::Ecc,
555            description: "k-NN similarity search".into(),
556            parameters: serde_json::json!({
557                "type": "object",
558                "properties": {
559                    "query": {"type": "array", "items": {"type": "number"}},
560                    "k": {"type": "integer", "default": 10}
561                },
562                "required": ["query"]
563            }),
564            gate_action: "ecc.search".into(),
565            effect: EffectVector {
566                risk: 0.05,
567                ..Default::default()
568            },
569            native: true,
570        });
571        catalog.push(BuiltinToolSpec {
572            name: "ecc.causal.link".into(),
573            category: ToolCategory::Ecc,
574            description: "Create causal edge".into(),
575            parameters: serde_json::json!({
576                "type": "object",
577                "properties": {
578                    "source": {"type": "integer"},
579                    "target": {"type": "integer"},
580                    "edge_type": {"type": "string"},
581                    "weight": {"type": "number", "default": 1.0}
582                },
583                "required": ["source", "target", "edge_type"]
584            }),
585            gate_action: "ecc.causal.link".into(),
586            effect: EffectVector {
587                risk: 0.3,
588                ..Default::default()
589            },
590            native: true,
591        });
592        catalog.push(BuiltinToolSpec {
593            name: "ecc.causal.query".into(),
594            category: ToolCategory::Ecc,
595            description: "Traverse causal graph".into(),
596            parameters: serde_json::json!({
597                "type": "object",
598                "properties": {
599                    "node": {"type": "integer"},
600                    "direction": {"type": "string", "enum": ["forward", "reverse"]},
601                    "depth": {"type": "integer", "default": 3}
602                },
603                "required": ["node"]
604            }),
605            gate_action: "ecc.causal.query".into(),
606            effect: EffectVector {
607                risk: 0.05,
608                ..Default::default()
609            },
610            native: true,
611        });
612        catalog.push(BuiltinToolSpec {
613            name: "ecc.crossref.create".into(),
614            category: ToolCategory::Ecc,
615            description: "Link nodes across structures".into(),
616            parameters: serde_json::json!({
617                "type": "object",
618                "properties": {
619                    "source_id": {"type": "string"},
620                    "target_id": {"type": "string"},
621                    "ref_type": {"type": "string"}
622                },
623                "required": ["source_id", "target_id", "ref_type"]
624            }),
625            gate_action: "ecc.crossref.create".into(),
626            effect: EffectVector {
627                risk: 0.2,
628                ..Default::default()
629            },
630            native: true,
631        });
632        catalog.push(BuiltinToolSpec {
633            name: "ecc.tick.status".into(),
634            category: ToolCategory::Ecc,
635            description: "Query cognitive tick state".into(),
636            parameters: serde_json::json!({"type": "object", "properties": {}}),
637            gate_action: "ecc.tick.status".into(),
638            effect: EffectVector {
639                risk: 0.05,
640                ..Default::default()
641            },
642            native: true,
643        });
644        catalog.push(BuiltinToolSpec {
645            name: "ecc.calibration.run".into(),
646            category: ToolCategory::Ecc,
647            description: "Re-run boot calibration".into(),
648            parameters: serde_json::json!({"type": "object", "properties": {}}),
649            gate_action: "ecc.calibration.run".into(),
650            effect: EffectVector {
651                risk: 0.1,
652                ..Default::default()
653            },
654            native: true,
655        });
656    }
657
658    catalog
659}
clawft_kernel/wasm_runner/catalog.rs

clawft_kernel/wasm_runner/
catalog.rs
