relay-code 0.1.0__py3-none-any.whl

tools/core/read.py

@@ -0,0 +1,129 @@
+from pydantic import BaseModel, Field
+from utils.paths import resolve_path, is_binary_file
+from utils.text import count_tokens, truncate_text
+from tools.base import Tool, ToolKind, ToolInvocation, ToolResult
+
+class ReadFileParams(BaseModel):
+
+    path: str = Field(
+        ...,
+        description='Path to the file to read (relative to the working dir or abs path)'
+    )
+
+    offset: int = Field(
+        1,
+        ge=1,
+        description='1-indexed line number to start reading from. Defaults to 1 (start of file). Minimum value is 1.'
+    )
+
+    limit: int | None = Field(
+        None,
+        ge=1,
+        description='Maximum number of lines to read starting from offset. If omitted, reads to the end of the file.'
+    )
+
+class ReadFileTool(Tool):
+    name = 'read'
+    description = (
+        "Read the contents of a file from the filesystem and return it as text with line numbers prefixed "
+        "(e.g. '1: import os'). If 'offset' exceeds the file's line count, returns an empty result. "
+        "Fails if the file does not exist, is a directory, or cannot be read (e.g. binary/permission errors). "
+        "Cannot read binary files (images, executables, etc.). "
+        "After reading the contents of the file, present the line numbers."
+    )
+    kind = ToolKind.READ
+
+    schema = ReadFileParams
+
+    MAX_FILE_SIZE = 1024 * 1024 * 10
+    MAX_OUTPUT_TOKENS = 25000
+
+    async def execute(self, invocation: ToolInvocation) -> ToolResult:
+        params = ReadFileParams(**invocation.params)
+        path = resolve_path(invocation.cwd, params.path)
+
+        if not path.exists():
+            return ToolResult.error_result(f"File not found at: {path}")
+
+        if not path.is_file():
+            return ToolResult.error_result(f"Path is not a file: {path}")
+
+        file_size = path.stat().st_size
+
+        if file_size > self.MAX_FILE_SIZE:
+            return ToolResult.error_result(
+                f"File too large ({file_size / (1024 * 1024):.1f}MB). "
+                f"The maximum file size is: {self.MAX_FILE_SIZE / (1024 * 1024):.0f}MB."
+            )
+
+        if is_binary_file(path):
+            file_size_mb = file_size / (1024 * 1024)
+            size_str = f"{file_size_mb:.2f}MB" if file_size_mb >= 1 else f"{file_size} bytes"
+            return ToolResult.error_result(
+                f"Cannot read binary file: {path.name} ({size_str}). "
+                f"This tool only reads text files."
+            )
+        try:
+            try:
+                content = path.read_text(encoding='utf-8')
+            except UnicodeDecodeError:
+                content = path.read_text(encoding='latin-1')
+
+            lines = content.splitlines()
+            total_lines = len(lines)
+
+            if total_lines == 0:
+                return ToolResult.success_result(
+                    "File is empty.", metadata={
+                        "lines": 0
+                    }
+                )
+
+            start_index = max(0, params.offset - 1)
+
+            if params.limit is not None:
+                end_index = min(start_index + params.limit, total_lines)
+            else:
+                end_index = total_lines
+
+            selected_lines = lines[start_index:end_index]
+            formatted_lines = []
+
+            for i, line in enumerate(selected_lines, start=start_index):
+                formatted_lines.append(f"{i + 1:6}|{line}")
+
+            output = "\n".join(formatted_lines)
+            token_count = count_tokens(output)
+
+            truncated = False
+            if token_count > self.MAX_OUTPUT_TOKENS:
+                output = truncate_text(
+                    output,
+                    "",
+                    self.MAX_OUTPUT_TOKENS,
+                    suffix=f"\n... [truncated] {total_lines} total lines."
+                )
+                truncated = True
+
+            metadata_lines = []
+            if start_index > 0 or end_index < total_lines:
+                metadata_lines.append(
+                    f"Showing lines {start_index + 1}-{end_index} of {total_lines}"
+                )
+
+            if metadata_lines:
+                header = ' | '.join(metadata_lines) + "\n\n"
+                output = header + output
+
+            return ToolResult.success_result(
+                output=output,
+                truncated=truncated,
+                metadata={
+                    'path': str(path),
+                    'total_lines': total_lines,
+                    'shown_start': start_index + 1,
+                    'shown_end': end_index,
+                },
+            )
+        except Exception as e:
+            return ToolResult.error_result(f"Error: failed to read file: {e}")

tools/core/shell.py

@@ -0,0 +1,162 @@
+import asyncio
+import os
+import fnmatch
+from pathlib import Path
+import signal
+import sys
+
+from pydantic import BaseModel, Field
+
+from tools.base import Tool, ToolInvocation, ToolKind, ToolResult
+
+DANGEROUS_COMMANDS = {
+    "rm -rf /",
+    "rm -rf ~",
+    "rm -rf /*",
+    "dd if=/dev/zero",
+    "dd if=/dev/random",
+    "mkfs",
+    "fdisk",
+    "parted",
+    ":(){ :|:& };:",  
+    "chmod 777 /",
+    "chmod -R 777",
+    "shutdown",
+    "reboot",
+    "halt",
+    "poweroff",
+    "init 0",
+    "init 6",
+    "sleep",
+}
+
+class ShellParams(BaseModel):
+
+    command: str = Field(
+        ...,
+        description='The shell command used to execute system commands',
+    )
+
+    timeout: int = Field(
+        120,
+        ge=1,
+        le=600,
+        description='Timeout in seconds (defaulted: 120s)'
+    )
+
+    cwd: str | None = Field(
+        None,
+        description='The working directory for the command to be ran'
+    )
+
+class ShellTool(Tool):
+
+    name = 'shell'
+    kind = ToolKind.SHELL
+    description = "Execute a shell command. Use this for running system wide commands, scripts and usage of CLI Tools."
+
+    schema = ShellParams
+
+    async def execute(self, invocation: ToolInvocation) -> ToolResult:
+        params = ShellParams(**invocation.params)
+
+        command = params.command.lower().strip()
+        for dangerous in DANGEROUS_COMMANDS:
+            if dangerous in command:
+                return ToolResult.error(
+                    f'Command blocked: {params.command}',
+                    metadata = {
+                        'blocked': True
+                    }
+                )
+        
+        if params.cwd:
+            cwd = Path(params.cwd)
+            if not cwd.is_absolute():
+                cwd = invocation.cwd / cwd
+        else:
+            cwd = invocation.cwd
+        
+        if not cwd.exists():
+            return ToolResult.error_result(
+                f"Working directory doesn't exist: {cwd}"
+            )
+        
+        env = self._build_environment()
+        if sys.platform == 'win32':
+            shell_cmd = ['cmd.exe', '/c', params.command]
+        else:
+            shell_cmd = ['/bin/bash', '-c', params.command]
+        
+        process = await asyncio.create_subprocess_exec(
+            *shell_cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=cwd,
+            env=env,
+            start_new_session=True,
+        )
+        try:
+            stdout_data, stderr_data = await asyncio.wait_for(
+                process.communicate(),
+                timeout = params.timeout
+            )
+        except asyncio.TimeoutError:
+            if sys.platform != 'win32':
+                os.killpg(os.getpgid(process.pid), signal.SIGKILL)
+            else:
+                process.kill()
+            await process.wait()
+            return ToolResult.error_result(
+                f'Command timed out after: {params.timeout}'
+            )
+        
+        exit_code = process.returncode
+
+        stdout = stdout_data.decode(
+            'utf-8',
+            errors='replace'
+        )
+
+        stderr = stderr_data.decode(
+            'utf-8',
+            errors='replace'
+        )
+
+        output = ""
+        if stdout.strip():
+            output += stdout.rstrip()
+        
+        if stderr.strip():
+            output += "\n--- stderr ---\n"
+            output += stderr.rstrip()
+        
+        if exit_code != 0:
+            output += f'\nExit code: {exit_code}'
+        
+        if len(output) > 100*1024:
+            output = output[: 100 * 1024] + "\n.. [output truncated]"
+        
+        return ToolResult(
+            success=exit_code==0,
+            output=output,
+            error=stderr if exit_code != 0 else None,
+            exit_code=exit_code,
+        )
+
+    def _build_environment(self) -> dict[str, str]:
+        env = os.environ.copy()
+
+        shell_environment = self.config.shell_environment
+
+        if not shell_environment.ignore_default_excludes:
+            for pattern in shell_environment.exclude_patterns:
+                keys_to_remove = [k for k in env.keys() if fnmatch.fnmatch(k.upper(), pattern.upper())]
+
+                for k in keys_to_remove:
+                    del env[k]
+
+        if shell_environment.set_vars:
+            env.update(shell_environment.set_vars)
+
+        return env

tools/core/todo.py

@@ -0,0 +1,135 @@
+import uuid
+from typing import Any
+
+from config.config import Config
+from tools.base import Tool, ToolInvocation, ToolKind, ToolResult
+from pydantic import BaseModel, Field
+
+PENDING = 'pending'
+COMPLETED = 'completed'
+
+
+class TodoParams(BaseModel):
+
+    action: str = Field(
+        ...,
+        description="Action: 'add', 'complete', 'list', 'clear'"
+    )
+
+    id: str | None = Field(
+        None,
+        description="A Todo ID (required for the 'complete' action)",
+    )
+
+    content: str | None = Field(
+        None,
+        description="The content for the 'add' action",
+    )
+
+
+class TodoTool(Tool):
+    name = 'todo'
+    description = 'Manage a task list for the current session, use this to track progress on more complex and multi-step tasks that can get resourse intensive.'
+    kind = ToolKind.MEMORY
+    schema = TodoParams
+
+    def __init__(self, config: Config) -> None:
+        super().__init__(config)
+        self._todos: dict[str, str] = {}
+        self._status: dict[str, str] = {}
+
+    def is_mutating(self, params: dict[str, Any]) -> bool:
+        return False
+
+    def _snapshot(self) -> dict[str, Any]:
+        todos = [
+            {'id': todo_id, 'content': content, 'status': self._status[todo_id]}
+            for todo_id, content in self._todos.items()
+        ]
+        return {
+            'todos': todos,
+            'completed': sum(1 for todo in todos if todo['status'] == COMPLETED),
+            'total': len(todos),
+        }
+
+    def _listing(self) -> str:
+        if not self._todos:
+            return "No todos."
+
+        snapshot = self._snapshot()
+        lines = [f"Todos ({snapshot['completed']}/{snapshot['total']} completed):"]
+
+        for todo in snapshot['todos']:
+            marker = 'x' if todo['status'] == COMPLETED else ' '
+            lines.append(f"  [{marker}] [{todo['id']}] {todo['content']}")
+
+        return "\n".join(lines)
+
+    async def execute(self, invocation: ToolInvocation) -> ToolResult:
+
+        params = TodoParams(**invocation.params)
+
+        try:
+            action = params.action.lower()
+
+            if action == 'add':
+                if not params.content:
+                    return ToolResult.error_result(
+                        "Content is required for the 'add' action."
+                    )
+
+                todo_id = str(uuid.uuid4())[:8]
+
+                self._todos[todo_id] = params.content
+                self._status[todo_id] = PENDING
+
+                return ToolResult.success_result(
+                    f"Added todo [{todo_id}]: {params.content}\n\n{self._listing()}",
+                    metadata=self._snapshot(),
+                )
+
+            elif action == 'complete':
+                if not params.id:
+                    return ToolResult.error_result(
+                        "An id is required for the 'complete' action."
+                    )
+                if params.id not in self._todos:
+                    return ToolResult.error_result(
+                        f"Todo not found: {params.id}"
+                    )
+
+                self._status[params.id] = COMPLETED
+                content = self._todos[params.id]
+
+                return ToolResult.success_result(
+                    f"Completed todo [{params.id}]: {content}\n\n{self._listing()}",
+                    metadata=self._snapshot(),
+                )
+
+            elif action == 'list':
+                return ToolResult.success_result(
+                    self._listing(),
+                    metadata=self._snapshot(),
+                )
+
+            elif action == 'clear':
+                count = len(self._todos)
+
+                self._todos.clear()
+                self._status.clear()
+
+                return ToolResult.success_result(
+                    f"Cleared {count} todo(s).",
+                    metadata=self._snapshot(),
+                )
+
+            else:
+                return ToolResult.error_result(
+                    f"Unknown action: {params.action}"
+                )
+
+        except Exception as e:
+
+            return ToolResult.error_result(
+                f"Unknown error: {e}"
+            )

tools/core/write.py

@@ -0,0 +1,76 @@
+from pathlib import Path
+from pydantic import BaseModel, Field
+from tools.base import FileDiff, Tool, ToolInvocation, ToolKind, ToolResult
+from utils.paths import ensure_parent_dir, resolve_path
+
+class WriteFileParams(BaseModel):
+    path: str = Field(
+        ...,
+        description='Path to the file to write, relative to the working or absolute path.'
+    )
+    content: str = Field(
+        ...,
+        description="Content to write to a file."
+    )
+    create_directories: bool = Field(
+        True,
+        description='Create parent directories if they are yet to exist.'
+    )
+
+class WriteFileTool(Tool):
+    name = 'write'
+    description = (
+        "Write contents to a file, creates a file if it doesn't exist, "
+        "or overwrites the file if it does. Parent directories are created automatically."
+        "Use this tool for creating new files or replacing file contents."
+        "For partial or smaller modifications, use the edit tool instead."
+    )
+    kind = ToolKind.WRITE
+    schema = WriteFileParams
+
+    async def execute(self, invocation: ToolInvocation) -> ToolResult:
+        params = WriteFileParams(**invocation.params)
+        path = resolve_path(invocation.cwd, params.path)
+
+        is_new_file = not path.exists()
+        old_content = ""
+
+        if not is_new_file:
+            try:
+                old_content = path.read_text(
+                    encoding='utf-8'
+                )
+            except:
+                pass
+        
+        try:
+            if params.create_directories:
+                ensure_parent_dir(path)
+            elif not path.parent.exists():
+                return ToolResult.error_result(f'Parent directory does not exist: {path.parent}')
+            path.write_text(params.content, encoding='utf-8')
+
+            action = "Created" if is_new_file else 'Updated'
+            line_count = len(params.content.splitlines())
+
+            return ToolResult.success_result(
+                f"{action} {path} {line_count} lines",
+                diff=FileDiff(
+                    path=path,
+                    old_content=old_content,
+                    new_content=params.content,
+                    is_new_file=is_new_file
+                ),
+                metadata = {
+                    'path': str(path),
+                    'is_new_file': is_new_file,
+                    'lines': line_count,
+                    'bytes': len(params.content.encode(
+                        'utf-8'
+                    ))
+                }
+            )
+        
+        except OSError as e:
+            return ToolResult.error_result(f"Failed to write file: {e}")
+        

tools/memory/memory.py

@@ -0,0 +1,191 @@
+import json
+import uuid
+from typing import Any
+
+from config.config import Config
+from config.loader import get_data_dir
+from tools.base import Tool, ToolInvocation, ToolKind, ToolResult
+from pydantic import BaseModel, Field
+
+
+class MemoryParams(BaseModel):
+
+    action: str = Field(
+        ...,
+        description="Action: 'set', 'get', 'delete', 'list', 'clear'"
+    )
+
+    key: str | None = Field(
+        None,
+        description="Memory key: required for set, get, delete.",
+    )
+
+    value: str | None = Field(
+        None,
+        description="Value to store (required for set)",
+    )
+
+
+class MemoryTool(Tool):
+    name = 'memory'
+    description = 'Store and retrieve persistent memory, use this tool to remember user information and preferences, for example: important context, user-specific details.'
+    kind = ToolKind.MEMORY
+    schema = MemoryParams
+
+    def _load_memory(self) -> dict:
+
+        data_dir = get_data_dir()
+
+        data_dir.mkdir(
+            parents=True, 
+            exist_ok=True
+        )
+
+        path = data_dir / 'user_memory.json'
+
+        if not path.exists():
+            return {
+                'entries': {}
+            }
+        
+        try:
+            content = path.read_text(
+                encoding='utf-8'
+            )
+            return json.loads(content)
+        except Exception:
+            return {
+                "entries": {}
+            }
+    
+    def _save_memory(self, memory: dict) -> None:
+
+        data_dir = get_data_dir()
+
+        data_dir.mkdir(
+            parents=True,
+            exist_ok=True
+        )
+
+        path = data_dir / 'user_memory.json'
+
+        path.write_text(json.dumps(
+            memory,
+            indent=2,
+            ensure_ascii=False
+            )
+        )
+
+    def _snapshot(
+        self,
+        memory: dict,
+        action: str,
+        key: str | None = None,
+    ) -> dict[str, Any]:
+        entries = memory.get('entries', {})
+        return {
+            'entries': [
+                {'key': k, 'value': v}
+                for k, v in sorted(entries.items())
+            ],
+            'count': len(entries),
+            'action': action,
+            'active_key': key,
+        }
+
+    async def execute(self, invocation: ToolInvocation):
+        
+        params = MemoryParams(**invocation.params)
+
+        try:
+            if params.action.lower() == "set":
+                if not params.key or not params.value:
+                    return ToolResult.error_result(
+                        "Key and value are required for set action."
+                    )
+                memory = self._load_memory()
+                memory['entries'][params.key] = params.value
+                self._save_memory(memory)
+
+                return ToolResult.success_result(
+                    f"Set memory: {params.key}",
+                    metadata=self._snapshot(memory, "set", params.key),
+                )
+
+            elif params.action.lower() == "get":
+                if not params.key:
+                    return ToolResult.error_result(
+                        "Key required for: 'get' action"
+                    )
+
+                memory = self._load_memory()
+                if params.key not in memory.get('entries', {}):
+                    return ToolResult.success_result(
+                        f"Memory not found: {params.key}",
+                        metadata=self._snapshot(memory, "get", params.key),
+                    )
+                return ToolResult.success_result(
+                        f"Memory found: {params.key}: {memory['entries'][params.key]}",
+                        metadata=self._snapshot(memory, "get", params.key),
+                    )
+            
+            elif params.action == "delete":
+                if not params.key:
+                    return ToolResult.error_result(
+                        "Key required for: 'delete' action"
+                    )
+                memory = self._load_memory()
+                if params.key not in memory.get('entries', {}):
+                    return ToolResult.success_result(
+                        f"Memory not found: {params.key}"
+                    )
+                
+                del memory['entries'][params.key]
+                self._save_memory(memory)
+
+                return ToolResult.success_result(
+                    f"Deleted memory: {params.key}",
+                    metadata=self._snapshot(memory, "delete", params.key),
+                )
+
+            elif params.action == "list":
+
+                memory = self._load_memory()
+                entries = memory.get('entries', {})
+
+                if not entries:
+                    return ToolResult.success_result(
+                        "No memory has been stored.",
+                        metadata=self._snapshot(memory, "list"),
+                    )
+
+                lines = [f"Stored memories:"]
+                for key, value in sorted(entries.items()):
+                    lines.append(f" {key}: {value}")
+
+                return ToolResult.success_result(
+                    "\n".join(lines),
+                    metadata=self._snapshot(memory, "list"),
+                )
+
+            elif params.action == "clear":
+
+                memory = self._load_memory()
+                count = len(memory.get('entries', {}))
+                memory['entries'] = {}
+                self._save_memory(memory)
+                return ToolResult.success_result(
+                    f"Cleared {count} entries",
+                    metadata=self._snapshot(memory, "clear"),
+                )
+
+            else:
+
+                return ToolResult.error_result(
+                    f"Unknown action: {params.action}"
+                )
+            
+        except Exception as e:
+            return ToolResult.error_result(
+                f"Something went wrong: {e}"
+            )