feat: implement tool registry and add various tools for HTTP, file operations, SSH, and Matrix messaging

tools/tool.go

@@ -0,0 +1,49 @@
+// Package tools defines tool specifications (pure) and their execution functions (impure).
+// Each tool is a pair: Def (pure data) + ToolFunc (impure execution).
+// To add a new tool, create a file in this package and register it in the agent builder.
+package tools
+
+import "context"
+
+// Def is the pure specification of a tool — only data, no side effects.
+type Def struct {
+	Name        string
+	Description string
+	Parameters  []Param
+}
+
+// Param describes a single parameter accepted by a tool.
+type Param struct {
+	Name        string
+	Type        string // "string", "number", "boolean", "integer", "object", "array"
+	Description string
+	Required    bool
+}
+
+// Result holds the outcome of executing a tool.
+type Result struct {
+	Output string
+	Err    error
+}
+
+// ToolFunc is the impure function that actually executes the tool.
+type ToolFunc func(ctx context.Context, args map[string]any) Result
+
+// Tool bundles a pure definition with its impure implementation.
+type Tool struct {
+	Def  Def
+	Exec ToolFunc
+}
+
+// getString extracts a string argument by name, returning "" if missing or wrong type.
+func getString(args map[string]any, key string) string {
+	v, ok := args[key]
+	if !ok {
+		return ""
+	}
+	s, ok := v.(string)
+	if !ok {
+		return ""
+	}
+	return s
+}