strix-agent 0.4.0__py3-none-any.whl

strix/tools/reporting/reporting_actions.py

@@ -0,0 +1,63 @@
+from typing import Any
+
+from strix.tools.registry import register_tool
+
+
+@register_tool(sandbox_execution=False)
+def create_vulnerability_report(
+    title: str,
+    content: str,
+    severity: str,
+) -> dict[str, Any]:
+    validation_error = None
+    if not title or not title.strip():
+        validation_error = "Title cannot be empty"
+    elif not content or not content.strip():
+        validation_error = "Content cannot be empty"
+    elif not severity or not severity.strip():
+        validation_error = "Severity cannot be empty"
+    else:
+        valid_severities = ["critical", "high", "medium", "low", "info"]
+        if severity.lower() not in valid_severities:
+            validation_error = (
+                f"Invalid severity '{severity}'. Must be one of: {', '.join(valid_severities)}"
+            )
+
+    if validation_error:
+        return {"success": False, "message": validation_error}
+
+    try:
+        from strix.telemetry.tracer import get_global_tracer
+
+        tracer = get_global_tracer()
+        if tracer:
+            report_id = tracer.add_vulnerability_report(
+                title=title,
+                content=content,
+                severity=severity,
+            )
+
+            return {
+                "success": True,
+                "message": f"Vulnerability report '{title}' created successfully",
+                "report_id": report_id,
+                "severity": severity.lower(),
+            }
+        import logging
+
+        logging.warning("Global tracer not available - vulnerability report not stored")
+
+        return {  # noqa: TRY300
+            "success": True,
+            "message": f"Vulnerability report '{title}' created successfully (not persisted)",
+            "warning": "Report could not be persisted - tracer unavailable",
+        }
+
+    except ImportError:
+        return {
+            "success": True,
+            "message": f"Vulnerability report '{title}' created successfully (not persisted)",
+            "warning": "Report could not be persisted - tracer module unavailable",
+        }
+    except (ValueError, TypeError) as e:
+        return {"success": False, "message": f"Failed to create vulnerability report: {e!s}"}

strix/tools/reporting/reporting_actions_schema.xml

@@ -0,0 +1,30 @@
+<tools>
+  <tool name="create_vulnerability_report">
+    <description>Create a vulnerability report for a discovered security issue.
+
+Use this tool to document a specific verified security vulnerability.
+Put ALL details in the content field - affected URLs, parameters, proof of concept, remediation steps, CVE references, CVSS scores, technical details, impact assessment, etc.
+
+DO NOT USE:
+- For general security observations without specific vulnerabilities
+- When you don't have concrete vulnerability details
+- When you don't have a proof of concept, or still not 100% sure if it's a vulnerability
+- For tracking multiple vulnerabilities (create separate reports)
+- For reporting multiple vulnerabilities at once. Use a separate create_vulnerability_report for each vulnerability.
+</description>
+    <parameters>
+      <parameter name="title" type="string" required="true">
+        <description>Clear, concise title of the vulnerability</description>
+      </parameter>
+      <parameter name="content" type="string" required="true">
+        <description>Complete vulnerability details including affected URLs, technical details, impact, proof of concept, remediation steps, and any relevant references. Be comprehensive and include everything relevant.</description>
+      </parameter>
+      <parameter name="severity" type="string" required="true">
+        <description>Severity level: critical, high, medium, low, or info</description>
+      </parameter>
+    </parameters>
+    <returns type="Dict[str, Any]">
+      <description>Response containing success status and message</description>
+    </returns>
+  </tool>
+</tools>

strix/tools/terminal/__init__.py

@@ -0,0 +1,4 @@
+from .terminal_actions import terminal_execute
+
+
+__all__ = ["terminal_execute"]

strix/tools/terminal/terminal_actions.py

@@ -0,0 +1,35 @@
+from typing import Any
+
+from strix.tools.registry import register_tool
+
+from .terminal_manager import get_terminal_manager
+
+
+@register_tool
+def terminal_execute(
+    command: str,
+    is_input: bool = False,
+    timeout: float | None = None,
+    terminal_id: str | None = None,
+    no_enter: bool = False,
+) -> dict[str, Any]:
+    manager = get_terminal_manager()
+
+    try:
+        return manager.execute_command(
+            command=command,
+            is_input=is_input,
+            timeout=timeout,
+            terminal_id=terminal_id,
+            no_enter=no_enter,
+        )
+    except (ValueError, RuntimeError) as e:
+        return {
+            "error": str(e),
+            "command": command,
+            "terminal_id": terminal_id or "default",
+            "content": "",
+            "status": "error",
+            "exit_code": None,
+            "working_dir": None,
+        }

strix/tools/terminal/terminal_actions_schema.xml

@@ -0,0 +1,146 @@
+<tools>
+  <tool name="terminal_execute">
+    <description>Execute a bash command in a persistent terminal session. The terminal maintains state (environment variables, current directory, running processes) between commands.</description>
+    <parameters>
+      <parameter name="command" type="string" required="true">
+        <description>The bash command to execute. Can be empty to check output of running commands (will wait for timeout period to collect output).
+
+        Supported special keys and sequences (based on official tmux key names):
+        - Control sequences: C-c, C-d, C-z, C-a, C-e, C-k, C-l, C-u, C-w, etc. (also ^c, ^d, etc.)
+        - Navigation keys: Up, Down, Left, Right, Home, End
+        - Page keys: PageUp, PageDown, PgUp, PgDn, PPage, NPage
+        - Function keys: F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12
+        - Special keys: Enter, Escape, Space, Tab, BTab, BSpace, DC, IC
+        - Note: Use official tmux names (BSpace not Backspace, DC not Delete, IC not Insert, Escape not Esc)
+        - Meta/Alt sequences: M-key (e.g., M-f, M-b) - tmux official modifier
+        - Shift sequences: S-key (e.g., S-F6, S-Tab, S-Left)
+        - Combined modifiers: C-S-key, C-M-key, S-M-key, etc.
+
+        Special keys work automatically - no need to set is_input=true for keys like C-c, C-d, etc.
+        These are useful for interacting with vim, emacs, REPLs, and other interactive applications.</description>
+      </parameter>
+      <parameter name="is_input" type="boolean" required="false">
+        <description>If true, the command is sent as input to a currently running process. If false (default), the command is executed as a new bash command.
+        Note: Special keys (C-c, C-d, etc.) automatically work when a process is running - you don't need to set is_input=true for them.
+        Use is_input=true for regular text input to running processes.</description>
+      </parameter>
+      <parameter name="timeout" type="number" required="false">
+        <description>Optional timeout in seconds for command execution. CAPPED AT 60 SECONDS. If not provided, uses default wait (30s). On timeout, the command keeps running and the tool returns with status 'running'. For truly long-running tasks, prefer backgrounding with '&'.</description>
+      </parameter>
+      <parameter name="terminal_id" type="string" required="false">
+        <description>Identifier for the terminal session. Defaults to "default". Use different IDs to manage multiple concurrent terminal sessions.</description>
+      </parameter>
+      <parameter name="no_enter" type="boolean" required="false">
+        <description>If true, don't automatically add Enter/newline after the command. Useful for:
+        - Interactive prompts where you want to send keys without submitting
+        - Navigation keys in full-screen applications
+
+        Examples:
+        - terminal_execute("gg", is_input=true, no_enter=true)  # Vim: go to top
+        - terminal_execute("5j", is_input=true, no_enter=true)  # Vim: move down 5 lines
+        - terminal_execute("i", is_input=true, no_enter=true)   # Vim: insert mode</description>
+      </parameter>
+    </parameters>
+    <returns type="Dict[str, Any]">
+      <description>Response containing:
+      - content: Command output
+      - exit_code: Exit code of the command (only for completed commands)
+      - command: The executed command
+      - terminal_id: The terminal session ID
+      - status: Command status ('completed' or 'running')
+      - working_dir: Current working directory after command execution</description>
+    </returns>
+    <notes>
+  Important usage rules:
+  1. PERSISTENT SESSION: The terminal maintains state between commands. Environment variables,
+     current directory, and running processes persist across multiple tool calls.
+
+  2. COMMAND EXECUTION:
+     - AVOID: Long pipelines, complex bash scripts, or convoluted one-liners
+     - Break complex operations into multiple simple tool calls for clarity and debugging
+     - For multiple commands, prefer separate tool calls over chaining with && or ;
+
+  3. LONG-RUNNING COMMANDS:
+     - Commands never get killed automatically - they keep running in background
+     - Set timeout to control how long to wait for output before returning
+     - For daemons/servers or very long jobs, append '&' to run in background
+     - Use empty command "" to check progress (waits for timeout period to collect output)
+     - Use C-c, C-d, C-z to interrupt processes (works automatically, no is_input needed)
+
+  4. TIMEOUT HANDLING:
+     - Timeout controls how long to wait before returning current output (max 60s cap)
+     - Commands are NEVER killed on timeout - they keep running
+     - After timeout, you can run new commands or check progress with empty command
+     - On timeout, status is 'running'; on completion, status is 'completed'
+
+  5. MULTIPLE TERMINALS: Use different terminal_id values to run multiple concurrent sessions.
+
+  6. INTERACTIVE PROCESSES:
+     - Special keys (C-c, C-d, etc.) work automatically when a process is running
+     - Use is_input=true for regular text input to running processes like:
+       * Interactive shells, REPLs, or prompts
+       * Long-running applications waiting for input
+       * Background processes that need interaction
+     - Use no_enter=true for stuff like Vim navigation, password typing, or multi-step commands
+
+  7. WORKING DIRECTORY: The terminal tracks and returns the current working directory.
+     Use absolute paths or cd commands to change directories as needed.
+
+  8. OUTPUT HANDLING: Large outputs are automatically truncated. The tool provides
+     the most relevant parts of the output for analysis.
+    </notes>
+    <examples>
+  # Execute a simple command
+  <function=terminal_execute>
+  <parameter=command>ls -la</parameter>
+  </function>
+
+  # Run a command with custom timeout
+  <function=terminal_execute>
+  <parameter=command>npm install</parameter>
+  <parameter=timeout>60</parameter>
+  </function>
+
+  # Check progress of running command (waits for timeout to collect output)
+  <function=terminal_execute>
+  <parameter=command></parameter>
+  <parameter=timeout>5</parameter>
+  </function>
+
+  # Start a background service
+  <function=terminal_execute>
+  <parameter=command>python app.py > server.log 2>&1 &</parameter>
+  </function>
+
+  # Interact with a running process
+  <function=terminal_execute>
+  <parameter=command>y</parameter>
+  <parameter=is_input>true</parameter>
+  </function>
+
+  # Interrupt a running process (special keys work automatically)
+  <function=terminal_execute>
+  <parameter=command>C-c</parameter>
+  </function>
+
+  # Send Escape key (use official tmux name)
+  <function=terminal_execute>
+  <parameter=command>Escape</parameter>
+  <parameter=is_input>true</parameter>
+  </function>
+
+  # Use a different terminal session
+  <function=terminal_execute>
+  <parameter=command>python3</parameter>
+  <parameter=terminal_id>python_session</parameter>
+  </function>
+
+  # Send input to Python REPL in specific session
+  <function=terminal_execute>
+  <parameter=command>print("Hello World")</parameter>
+  <parameter=is_input>true</parameter>
+  <parameter=terminal_id>python_session</parameter>
+  </function>
+    </examples>
+  </tool>
+</tools>

strix/tools/terminal/terminal_manager.py

@@ -0,0 +1,151 @@
+import atexit
+import contextlib
+import signal
+import sys
+import threading
+from typing import Any
+
+from .terminal_session import TerminalSession
+
+
+class TerminalManager:
+    def __init__(self) -> None:
+        self.sessions: dict[str, TerminalSession] = {}
+        self._lock = threading.Lock()
+        self.default_terminal_id = "default"
+        self.default_timeout = 30.0
+
+        self._register_cleanup_handlers()
+
+    def execute_command(
+        self,
+        command: str,
+        is_input: bool = False,
+        timeout: float | None = None,
+        terminal_id: str | None = None,
+        no_enter: bool = False,
+    ) -> dict[str, Any]:
+        if terminal_id is None:
+            terminal_id = self.default_terminal_id
+
+        session = self._get_or_create_session(terminal_id)
+
+        try:
+            result = session.execute(command, is_input, timeout or self.default_timeout, no_enter)
+
+            return {
+                "content": result["content"],
+                "command": command,
+                "terminal_id": terminal_id,
+                "status": result["status"],
+                "exit_code": result.get("exit_code"),
+                "working_dir": result.get("working_dir"),
+            }
+
+        except RuntimeError as e:
+            return {
+                "error": str(e),
+                "command": command,
+                "terminal_id": terminal_id,
+                "content": "",
+                "status": "error",
+                "exit_code": None,
+                "working_dir": None,
+            }
+        except OSError as e:
+            return {
+                "error": f"System error: {e}",
+                "command": command,
+                "terminal_id": terminal_id,
+                "content": "",
+                "status": "error",
+                "exit_code": None,
+                "working_dir": None,
+            }
+
+    def _get_or_create_session(self, terminal_id: str) -> TerminalSession:
+        with self._lock:
+            if terminal_id not in self.sessions:
+                self.sessions[terminal_id] = TerminalSession(terminal_id)
+            return self.sessions[terminal_id]
+
+    def close_session(self, terminal_id: str | None = None) -> dict[str, Any]:
+        if terminal_id is None:
+            terminal_id = self.default_terminal_id
+
+        with self._lock:
+            if terminal_id not in self.sessions:
+                return {
+                    "terminal_id": terminal_id,
+                    "message": f"Terminal '{terminal_id}' not found",
+                    "status": "not_found",
+                }
+
+            session = self.sessions.pop(terminal_id)
+
+        try:
+            session.close()
+        except (RuntimeError, OSError) as e:
+            return {
+                "terminal_id": terminal_id,
+                "error": f"Failed to close terminal '{terminal_id}': {e}",
+                "status": "error",
+            }
+        else:
+            return {
+                "terminal_id": terminal_id,
+                "message": f"Terminal '{terminal_id}' closed successfully",
+                "status": "closed",
+            }
+
+    def list_sessions(self) -> dict[str, Any]:
+        with self._lock:
+            session_info: dict[str, dict[str, Any]] = {}
+            for tid, session in self.sessions.items():
+                session_info[tid] = {
+                    "is_running": session.is_running(),
+                    "working_dir": session.get_working_dir(),
+                }
+
+        return {"sessions": session_info, "total_count": len(session_info)}
+
+    def cleanup_dead_sessions(self) -> None:
+        with self._lock:
+            dead_sessions: list[str] = []
+            for tid, session in self.sessions.items():
+                if not session.is_running():
+                    dead_sessions.append(tid)
+
+            for tid in dead_sessions:
+                session = self.sessions.pop(tid)
+                with contextlib.suppress(Exception):
+                    session.close()
+
+    def close_all_sessions(self) -> None:
+        with self._lock:
+            sessions_to_close = list(self.sessions.values())
+            self.sessions.clear()
+
+        for session in sessions_to_close:
+            with contextlib.suppress(Exception):
+                session.close()
+
+    def _register_cleanup_handlers(self) -> None:
+        atexit.register(self.close_all_sessions)
+
+        signal.signal(signal.SIGTERM, self._signal_handler)
+        signal.signal(signal.SIGINT, self._signal_handler)
+
+        if hasattr(signal, "SIGHUP"):
+            signal.signal(signal.SIGHUP, self._signal_handler)
+
+    def _signal_handler(self, _signum: int, _frame: Any) -> None:
+        self.close_all_sessions()
+        sys.exit(0)
+
+
+_terminal_manager = TerminalManager()
+
+
+def get_terminal_manager() -> TerminalManager:
+    return _terminal_manager