flowent 0.0.1 → 0.0.5

package/backend/src/flowent/tools/create_tab.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from flowent.graph_service import create_tab, serialize_tab_summary
+from flowent.models import NodeType
+from flowent.tools import Tool
+
+if TYPE_CHECKING:
+    from flowent.agent import Agent
+
+
+class CreateTabTool(Tool):
+    name = "create_workflow"
+    description = "Create a new workflow with its own permission boundary."
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "title": {
+                "type": "string",
+                "description": "Human-readable workflow title",
+            },
+            "allow_network": {
+                "type": "boolean",
+                "description": "Whether this workflow should have network access (default False)",
+            },
+            "write_dirs": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "List of directory paths this workflow is allowed to write to",
+            },
+        },
+        "required": ["title"],
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **_kwargs: Any) -> str:
+        if agent.node_type != NodeType.ASSISTANT:
+            return json.dumps({"error": "Only the Assistant may create workflows"})
+
+        title = args.get("title")
+        allow_network = args.get("allow_network", False)
+        write_dirs = args.get("write_dirs", [])
+        if not isinstance(title, str) or not title.strip():
+            return json.dumps({"error": "title must be a non-empty string"})
+        if not isinstance(allow_network, bool):
+            return json.dumps({"error": "allow_network must be a boolean"})
+        if not isinstance(write_dirs, list) or not all(
+            isinstance(x, str) for x in write_dirs
+        ):
+            return json.dumps({"error": "write_dirs must be a list of strings"})
+
+        try:
+            tab = create_tab(
+                title=title,
+                allow_network=allow_network,
+                write_dirs=write_dirs,
+            )
+        except ValueError as exc:
+            return json.dumps({"error": str(exc)})
+        return json.dumps(serialize_tab_summary(tab))

package/backend/src/flowent/tools/delete_tab.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from flowent.graph_service import delete_tab
+from flowent.models import NodeType
+from flowent.tools import Tool
+
+if TYPE_CHECKING:
+    from flowent.agent import Agent
+
+
+class DeleteTabTool(Tool):
+    name = "delete_workflow"
+    description = "Delete a workflow and clean up its graph."
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "workflow_id": {
+                "type": "string",
+                "description": "ID of the workflow to delete",
+            }
+        },
+        "required": ["workflow_id"],
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **_kwargs: Any) -> str:
+        if agent.node_type != NodeType.ASSISTANT:
+            return json.dumps({"error": "Only the Assistant may delete workflows"})
+
+        workflow_id = args.get("workflow_id")
+        if not isinstance(workflow_id, str) or not workflow_id.strip():
+            return json.dumps({"error": "workflow_id must be a non-empty string"})
+
+        deleted, error = delete_tab(tab_id=workflow_id.strip())
+        if error is not None or deleted is None:
+            return json.dumps({"error": error or "Failed to delete workflow"})
+        return json.dumps(deleted)

package/backend/src/flowent/tools/edit.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Callable
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from loguru import logger
+
+from flowent.tools import Tool, re_raise_interrupt
+
+if TYPE_CHECKING:
+    from flowent.agent import Agent
+
+
+class EditTool(Tool):
+    name = "edit"
+    description = (
+        "Apply one or more line-based edits to a file in order. "
+        "Use the read tool first to get the exact line numbers. "
+        "Each edit uses 1-indexed inclusive start_line and end_line. "
+        "new_content replaces those lines exactly as given (include a trailing newline if needed). "
+        "If the file does not exist it will be created."
+    )
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "Absolute path to the file to edit or create",
+            },
+            "edits": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "start_line": {
+                            "type": "integer",
+                            "description": "First line to replace (1-indexed, inclusive). Use 1 for a new file.",
+                        },
+                        "end_line": {
+                            "type": "integer",
+                            "description": "Last line to replace (1-indexed, inclusive).",
+                        },
+                        "new_content": {
+                            "type": "string",
+                            "description": "Replacement text for the specified line range. Use an empty string to delete lines.",
+                        },
+                    },
+                    "required": ["start_line", "end_line", "new_content"],
+                },
+                "description": "Edits to apply in order. Later line numbers are based on the file state after earlier edits.",
+            },
+        },
+        "required": ["path", "edits"],
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **kwargs: Any) -> str:
+        path_str = args["path"]
+        real_path = Path(path_str)
+        on_output: Callable[[str], None] | None = kwargs.get("on_output")
+
+        try:
+            edits = args["edits"]
+            if not isinstance(edits, list):
+                return json.dumps({"error": "edits must be an array"})
+
+            if not real_path.exists():
+                os.makedirs(real_path.parent, exist_ok=True)
+                real_path.write_text("", encoding="utf-8")
+                if on_output is not None:
+                    on_output(f"Created {path_str}\n")
+
+            with open(real_path, encoding="utf-8") as f:
+                lines = f.readlines()
+
+            applied_edits: list[dict[str, int | str]] = []
+            for index, raw_edit in enumerate(edits, start=1):
+                if not isinstance(raw_edit, dict):
+                    return json.dumps({"error": "each edit must be an object"})
+
+                start_line = int(raw_edit["start_line"])
+                end_line = int(raw_edit["end_line"])
+                new_content: str = raw_edit["new_content"]
+
+                if start_line < 1:
+                    return json.dumps({"error": "start_line must be >= 1"})
+                if end_line < start_line:
+                    return json.dumps({"error": "end_line must be >= start_line"})
+
+                total_lines = len(lines)
+                if start_line > total_lines + 1:
+                    return json.dumps(
+                        {
+                            "error": f"start_line {start_line} exceeds file length {total_lines}"
+                        }
+                    )
+
+                current_end_line = min(end_line, total_lines)
+                if on_output is not None:
+                    on_output(
+                        f"Applying edit {index}/{len(edits)} at lines {start_line}-{current_end_line}\n"
+                    )
+
+                replacement = []
+                if new_content:
+                    replacement = new_content.splitlines(keepends=True)
+                    if replacement and not replacement[-1].endswith("\n"):
+                        replacement[-1] += "\n"
+
+                lines = lines[: start_line - 1] + replacement + lines[current_end_line:]
+                applied_edits.append(
+                    {
+                        "start_line": start_line,
+                        "end_line": current_end_line,
+                        "replacement_line_count": len(replacement),
+                    }
+                )
+
+            with open(real_path, "w", encoding="utf-8") as f:
+                f.writelines(lines)
+            if on_output is not None:
+                on_output(f"Wrote {path_str}\n")
+
+            logger.debug(
+                "Edited file: {} ({} edit(s), new_line_count={})",
+                path_str,
+                len(applied_edits),
+                len(lines),
+            )
+            return json.dumps(
+                {
+                    "status": "edited",
+                    "path": path_str,
+                    "applied_edits": applied_edits,
+                    "new_line_count": len(lines),
+                }
+            )
+        except Exception as e:
+            re_raise_interrupt(agent, e)
+            return json.dumps({"error": str(e)})

package/backend/src/flowent/tools/exec.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import threading
+from collections.abc import Callable
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from loguru import logger
+
+from flowent.sandbox import build_bwrap_cmd
+from flowent.tools import Tool, re_raise_interrupt
+
+if TYPE_CHECKING:
+    from flowent.agent import Agent
+
+
+class ExecTool(Tool):
+    name = "exec"
+    description = "Execute a shell command in a sandboxed environment."
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "command": {
+                "type": "string",
+                "description": "Shell command to execute",
+            },
+            "timeout": {
+                "type": "number",
+                "description": "Timeout in seconds (default 30)",
+            },
+        },
+        "required": ["command"],
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **kwargs: Any) -> str:
+        on_output: Callable[[str], None] | None = kwargs.get("on_output")
+        from flowent.graph_service import resolve_effective_permissions_for_agent
+        from flowent.settings import get_runtime_working_dir_path
+
+        command = args["command"]
+        timeout = int(args.get("timeout", 30))
+        allow_network, write_dirs = resolve_effective_permissions_for_agent(agent)
+        cwd = Path(get_runtime_working_dir_path())
+
+        bwrap_cmd = build_bwrap_cmd(
+            write_dirs,
+            command,
+            allow_network=allow_network,
+            cwd=cwd,
+        )
+
+        logger.debug(
+            "Executing command: {} (timeout={}s, cwd={})",
+            command,
+            timeout,
+            cwd,
+        )
+
+        proc: subprocess.Popen[str] | None = None
+        try:
+            proc = subprocess.Popen(
+                bwrap_cmd,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                cwd=str(cwd),
+            )
+            agent.set_interrupt_callback(
+                lambda: proc.kill() if proc.poll() is None else None
+            )
+
+            stdout_lines: list[str] = []
+            stderr_lines: list[str] = []
+
+            def _read_stderr() -> None:
+                assert proc.stderr is not None
+                for line in proc.stderr:
+                    stderr_lines.append(line)
+
+            stderr_thread = threading.Thread(target=_read_stderr, daemon=True)
+            stderr_thread.start()
+
+            assert proc.stdout is not None
+            for line in proc.stdout:
+                stdout_lines.append(line)
+                if on_output:
+                    on_output(line)
+
+            try:
+                proc.wait(timeout=timeout)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                proc.wait()
+                logger.warning("Command timed out after {}s: {}", timeout, command)
+                return json.dumps({"error": f"Command timed out after {timeout}s"})
+
+            stderr_thread.join(timeout=5)
+
+            stdout = "".join(stdout_lines)
+            stderr = "".join(stderr_lines)
+            logger.debug("Command exited with code {}", proc.returncode)
+            return json.dumps(
+                {
+                    "returncode": proc.returncode,
+                    "stdout": stdout[:5000],
+                    "stderr": stderr[:2000],
+                }
+            )
+        except Exception as e:
+            if proc is not None and proc.poll() is None:
+                proc.kill()
+                proc.wait()
+            re_raise_interrupt(agent, e)
+            return json.dumps({"error": str(e)})
+        finally:
+            agent.set_interrupt_callback(None)

package/backend/src/flowent/tools/fetch.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from loguru import logger
+
+from flowent.network import create_http_session, iter_response_text
+from flowent.tools import Tool, re_raise_interrupt
+
+if TYPE_CHECKING:
+    from flowent.agent import Agent
+
+
+class FetchTool(Tool):
+    name = "fetch"
+    description = "Make an HTTP request."
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "method": {
+                "type": "string",
+                "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"],
+                "description": "HTTP method",
+            },
+            "url": {"type": "string", "description": "Request URL"},
+            "headers": {
+                "type": "object",
+                "description": "Request headers (optional)",
+            },
+            "body": {"type": "string", "description": "Request body (optional)"},
+        },
+        "required": ["method", "url"],
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **kwargs: Any) -> str:
+        method = args["method"]
+        url = args["url"]
+        on_output: Callable[[str], None] | None = kwargs.get("on_output")
+        logger.debug("HTTP {} {}", method, url)
+        try:
+            with (
+                create_http_session(timeout=30.0, impersonate_browser=True) as client,
+                client.stream(
+                    method,
+                    url,
+                    headers=args.get("headers"),
+                    data=args.get("body"),
+                ) as response,
+            ):
+                close_response = getattr(response, "close", None)
+                agent.set_interrupt_callback(
+                    close_response if callable(close_response) else None
+                )
+                if on_output is not None:
+                    on_output(f"{method} {url}\n")
+                    on_output(f"HTTP {response.status_code}\n\n")
+
+                remaining = 5000
+                body_parts: list[str] = []
+                for chunk in iter_response_text(response):
+                    if not chunk or remaining <= 0:
+                        continue
+                    if len(chunk) > remaining:
+                        chunk = chunk[:remaining]
+                    body_parts.append(chunk)
+                    remaining -= len(chunk)
+                    if on_output is not None:
+                        on_output(chunk)
+
+            body = "".join(body_parts)
+            logger.debug("HTTP {} {} -> {}", method, url, response.status_code)
+            return json.dumps(
+                {
+                    "status_code": response.status_code,
+                    "body": body,
+                }
+            )
+        except Exception as e:
+            re_raise_interrupt(agent, e)
+            logger.warning("HTTP request failed: {} {} - {}", method, url, e)
+            return json.dumps({"error": str(e)})
+        finally:
+            agent.set_interrupt_callback(None)

package/backend/src/flowent/tools/idle.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from flowent.tools import Tool
+
+if TYPE_CHECKING:
+    from flowent.agent import Agent
+
+
+class IdleTool(Tool):
+    name = "idle"
+    description = (
+        "Enter idle state. The agent suspends execution until a wake signal re-activates it. "
+        "Use this when the current step or task is finished, paused, or blocked, and there is no "
+        "immediate next action to take right now. Incoming messages will automatically re-activate you as new input messages, and the tool returns the idle duration when execution resumes."
+    )
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {},
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **kwargs: Any) -> str:
+        tool_call_id = kwargs.get("tool_call_id")
+        if tool_call_id is not None and not isinstance(tool_call_id, str):
+            tool_call_id = None
+        return agent.request_idle(tool_call_id=tool_call_id)

package/backend/src/flowent/tools/list_roles.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from flowent.tools import Tool
+
+if TYPE_CHECKING:
+    from flowent.agent import Agent
+
+
+class ListRolesTool(Tool):
+    name = "list_roles"
+    description = "List all registered roles with builtin and optional tool views."
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {},
+        "required": [],
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **_kwargs: Any) -> str:
+        from flowent.models import NodeType
+        from flowent.settings import get_settings, normalize_tool_names
+        from flowent.tools import (
+            MINIMUM_TOOLS,
+            build_tool_registry,
+            is_assistant_only_mcp_tool_name,
+            is_assistant_only_tool_name,
+        )
+
+        settings = get_settings()
+        tool_registry = build_tool_registry()
+        all_tool_names: list[str] = []
+        for tool in tool_registry.list_tools(agent_visible_only=True):
+            descriptor = getattr(tool, "_descriptor", None)
+            descriptor_tool_name = getattr(descriptor, "tool_name", None)
+            if isinstance(
+                descriptor_tool_name, str
+            ) and is_assistant_only_mcp_tool_name(descriptor_tool_name):
+                continue
+            all_tool_names.append(tool.name)
+        if agent.node_type != NodeType.ASSISTANT:
+            all_tool_names = [
+                tool_name
+                for tool_name in all_tool_names
+                if not is_assistant_only_tool_name(tool_name)
+            ]
+        payload: list[dict[str, object]] = []
+
+        for role in settings.roles:
+            builtin_tools = normalize_tool_names([*MINIMUM_TOOLS, *role.included_tools])
+            if agent.node_type != NodeType.ASSISTANT:
+                builtin_tools = [
+                    tool_name
+                    for tool_name in builtin_tools
+                    if not is_assistant_only_tool_name(tool_name)
+                    and not is_assistant_only_mcp_tool_name(tool_name)
+                ]
+            optional_tools = [
+                tool_name
+                for tool_name in all_tool_names
+                if tool_name not in builtin_tools
+                and tool_name not in role.excluded_tools
+            ]
+            payload.append(
+                {
+                    "name": role.name,
+                    "description": role.description,
+                    "system_prompt": role.system_prompt,
+                    "builtin_tools": builtin_tools,
+                    "optional_tools": optional_tools,
+                }
+            )
+
+        return json.dumps(payload)

package/backend/src/flowent/tools/list_tabs.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from flowent.graph_service import (
+    is_tab_leader,
+    list_tab_edges,
+    list_tab_nodes,
+    list_workflow_nodes,
+    serialize_tab_summary,
+)
+from flowent.models import NodeType
+from flowent.tools import Tool
+from flowent.workspace_store import workspace_store
+
+if TYPE_CHECKING:
+    from flowent.agent import Agent
+
+
+class ListTabsTool(Tool):
+    name = "list_workflows"
+    description = "List persistent workflows. Optionally include the full Workflow Graph for one workflow."
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "workflow_id": {
+                "type": "string",
+                "description": "Optional workflow ID to inspect in detail",
+            }
+        },
+        "required": [],
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **_kwargs: Any) -> str:
+        if agent.node_type != NodeType.ASSISTANT:
+            return json.dumps({"error": "Only the Assistant may list workflows"})
+
+        workflow_id = args.get("workflow_id")
+        if workflow_id is not None and not isinstance(workflow_id, str):
+            return json.dumps({"error": "workflow_id must be a string"})
+
+        if isinstance(workflow_id, str) and workflow_id.strip():
+            tab = workspace_store.get_tab(workflow_id.strip())
+            if tab is None:
+                return json.dumps(
+                    {"error": f"Workflow '{workflow_id.strip()}' not found"}
+                )
+            nodes = [
+                {
+                    "id": node.id,
+                    "node_type": node.type.value,
+                    "name": (
+                        node.config["name"]
+                        if isinstance(node.config.get("name"), str)
+                        else None
+                    ),
+                    "role_name": (
+                        node.config["role_name"]
+                        if isinstance(node.config.get("role_name"), str)
+                        else None
+                    ),
+                    "is_leader": False,
+                    "position": (
+                        tab.definition.view.positions[node.id].serialize()
+                        if node.id in tab.definition.view.positions
+                        else None
+                    ),
+                }
+                for node in list_workflow_nodes(tab.id)
+            ]
+            return json.dumps(
+                {
+                    "workflow": serialize_tab_summary(tab),
+                    "nodes": nodes,
+                    "runtime_nodes": [
+                        {
+                            "id": node.id,
+                            "name": node.config.name,
+                            "role_name": node.config.role_name,
+                            "is_leader": is_tab_leader(
+                                node_id=node.id,
+                                tab_id=tab.id,
+                            ),
+                            "state": node.state.value,
+                            "position": (
+                                node.position.serialize()
+                                if node.position is not None
+                                else None
+                            ),
+                        }
+                        for node in list_tab_nodes(tab.id)
+                    ],
+                    "edges": [edge.serialize() for edge in list_tab_edges(tab.id)],
+                }
+            )
+
+        return json.dumps(
+            [serialize_tab_summary(tab) for tab in workspace_store.list_tabs()]
+        )

package/backend/src/flowent/tools/list_tools.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from flowent.tools import Tool
+
+if TYPE_CHECKING:
+    from flowent.agent import Agent
+
+
+class ListToolsTool(Tool):
+    name = "list_tools"
+    description = "List all registered tools with their names and descriptions."
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {},
+        "required": [],
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **_kwargs: Any) -> str:
+        from flowent.models import NodeType
+        from flowent.tools import list_agent_visible_tool_descriptors
+
+        descriptors = list_agent_visible_tool_descriptors(
+            include_assistant_only=agent.node_type == NodeType.ASSISTANT
+        )
+        return json.dumps(descriptors)