misc: small fix or general refactoring i did not bother commenting

Author: evilsocket

docs/assets/make_ns.py

@@ -32,6 +32,26 @@
 
             print(doc.strip())
             print()
+
+            if hasattr(module, "jail"):
+                print("### Jail")
+                print()
+                print(
+                    "The tools in this namespace can be restricted to a specific set of paths by using the `jail` directive in the agent configuration:"
+                )
+
+                print()
+                print("```yaml")
+                print("using:")
+                print(f"  - {modname}")
+                print()
+                print("jail:")
+                print(f"    {modname}:")
+                print('      - "/only/path/to/allow"')
+                print('      - "{{ target_path }}" # variables can be used too')
+                print("```")
+                print()
+
             print("<details>")
             print("<summary><b>Show Tools</b></summary>")
             print()
@@ -77,5 +97,7 @@
 
                         print(f"* `{param_name}` <i>({base_type})</i>: {description.strip()}")
 
+                    print()
+
             print("</details>")
             print()

docs/namespaces.md

@@ -17,6 +17,7 @@ Let the agent create its own tools in Python.
 **Parameters**
 
 * `code` <i>(<class 'str'>)</i>: The Python code to create the tool.
+
 </details>
 
 ## 💻 computer
@@ -41,13 +42,15 @@ Computer use primitives for mouse, keyboard, and screen.
 **Parameters**
 
 * `keys` <i>(<class 'str'>)</i>: The hotkey sequence to press (like 'ctrl+shift+cmd+space')
+
 ### `keyboard_type`
 
 <pre>Type the given text on the keyboard.</pre>
 
 **Parameters**
 
 * `text` <i>(<class 'str'>)</i>: The text to type
+
 ### `mouse_double_click`
 
 <pre>Double click the left mouse button at the current mouse position.</pre>
@@ -64,6 +67,7 @@ Computer use primitives for mouse, keyboard, and screen.
 
 * `x` <i>(<class 'int'>)</i>: The x coordinate to move to
 * `y` <i>(<class 'int'>)</i>: The y coordinate to move to
+
 ### `mouse_middle_click`
 
 <pre>Click the middle mouse button at the current mouse position.</pre>
@@ -76,6 +80,7 @@ Computer use primitives for mouse, keyboard, and screen.
 
 * `x` <i>(<class 'int'>)</i>: The x coordinate to move to
 * `y` <i>(<class 'int'>)</i>: The y coordinate to move to
+
 ### `mouse_right_click`
 
 <pre>Click the right mouse button at the current mouse position.</pre>
@@ -88,6 +93,7 @@ Computer use primitives for mouse, keyboard, and screen.
 
 * `x` <i>(<class 'int'>)</i>: The x coordinate to move to
 * `y` <i>(<class 'int'>)</i>: The y coordinate to move to
+
 ### `screenshot`
 
 <pre>Take a screenshot of the current screen.</pre>
@@ -98,6 +104,20 @@ Computer use primitives for mouse, keyboard, and screen.
 
 Read-only access primitives to the local filesystem.
 
+### Jail
+
+The tools in this namespace can be restricted to a specific set of paths by using the `jail` directive in the agent configuration:
+
+```yaml
+using:
+  - filesystem
+
+jail:
+    filesystem:
+      - "/only/path/to/allow"
+      - "{{ target_path }}" # variables can be used too
+```
+
 <details>
 <summary><b>Show Tools</b></summary>
 
@@ -108,13 +128,15 @@ Read-only access primitives to the local filesystem.
 **Parameters**
 
 * `path` <i>(<class 'str'>)</i>: The path to the folder to list
+
 ### `read_file`
 
 <pre>Read the contents of a file from disk.</pre>
 
 **Parameters**
 
 * `path` <i>(<class 'str'>)</i>: The path to the file to read
+
 </details>
 
 ## 💬 inquire
@@ -132,6 +154,7 @@ Let the agent interactively ask questions to the user in a structured way.
 
 * `question` <i>(<class 'str'>)</i>: The question to ask the user.
 * `default` <i>(<class 'bool'>)</i>: The default answer to the question.
+
 ### `ask_for_multiple_choice`
 
 <pre>Ask a multiple choice question to the user.</pre>
@@ -140,6 +163,7 @@ Let the agent interactively ask questions to the user in a structured way.
 
 * `question` <i>(<class 'str'>)</i>: The question to ask the user.
 * `choices` <i>(list[str])</i>: The choices to offer the user.
+
 ### `ask_for_single_choice`
 
 <pre>Ask a single choice question to the user.</pre>
@@ -148,13 +172,15 @@ Let the agent interactively ask questions to the user in a structured way.
 
 * `question` <i>(<class 'str'>)</i>: The question to ask the user.
 * `choices` <i>(list[str])</i>: The choices to offer the user.
+
 ### `ask_question`
 
 <pre>Ask a question to the user.</pre>
 
 **Parameters**
 
 * `question` <i>(<class 'str'>)</i>: The question to ask the user.
+
 </details>
 
 ## 🧠 reasoning
@@ -197,6 +223,7 @@ Simulates the reasoning process at runtime.
 **Parameters**
 
 * `thought` <i>(<class 'str'>)</i>: A thought to think about
+
 </details>
 
 ## 💻 shell
@@ -213,6 +240,7 @@ Let the agent execute shell commands.
 **Parameters**
 
 * `command` <i>(<class 'str'>)</i>: The shell command to execute
+
 </details>
 
 ## ✅ task
@@ -229,13 +257,15 @@ Let the agent autonomously set the task as complete or failed.
 **Parameters**
 
 * `reason` <i>(str | None)</i>: Optional reason why the task is complete or report of conclusive information.
+
 ### `task_failed`
 
 <pre>Use this tool if you determine that the given goal or task is impossible given the information you have.</pre>
 
 **Parameters**
 
 * `reason` <i>(<class 'str'>)</i>: The reason why the task is impossible
+
 </details>
 
 ## 🕒 time
@@ -256,5 +286,6 @@ Provides tools for getting the current date and time and waiting for a given num
 **Parameters**
 
 * `seconds` <i>(<class 'int'>)</i>: The number of seconds to wait
+
 </details>
 

nerve/models.py

@@ -64,8 +64,6 @@ class Configuration(BaseModel):
     # legacy field used to detect if the user is loading a legacy file
     system_prompt: str | None = Field(default=None, exclude=True)
 
-    # TODO: document these fields.
-
     # used for versioning the agents
     version: str = "1.0.0"
     # the system prompt, the agent identity