flowent 0.0.0 → 0.0.4

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

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from flowent.mcp_service import MCPToolDescriptor, mcp_service
+from flowent.tools import Tool
+
+if TYPE_CHECKING:
+    from flowent.agent import Agent
+
+
+class DynamicMCPTool(Tool):
+    agent_visible = True
+    llm_visible = True
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {},
+        "required": [],
+    }
+
+    def __init__(self, descriptor: MCPToolDescriptor) -> None:
+        self._descriptor = descriptor
+        self.name = descriptor.fully_qualified_id
+        self.description = descriptor.description or f"MCP tool {descriptor.tool_name}"
+        self._parameters = descriptor.input_schema or {
+            "type": "object",
+            "properties": {},
+            "required": [],
+        }
+
+    def to_schema(self) -> dict[str, Any]:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self._parameters,
+            },
+        }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **_kwargs: Any) -> str:
+        result = mcp_service.call_agent_tool(
+            agent,
+            fully_qualified_id=self._descriptor.fully_qualified_id,
+            arguments=args,
+        )
+        return json.dumps(result, ensure_ascii=False)
+
+
+class ListMCPResourcesTool(Tool):
+    name = "list_mcp_resources"
+    description = "List MCP resources visible in the current execution boundary."
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "server_name": {
+                "type": "string",
+                "description": "Optional globally available MCP server name filter",
+            }
+        },
+        "required": [],
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **_kwargs: Any) -> str:
+        server_name = args.get("server_name")
+        resources = mcp_service.list_agent_resources(
+            agent,
+            server_name=server_name
+            if isinstance(server_name, str) and server_name.strip()
+            else None,
+        )
+        return json.dumps(resources, ensure_ascii=False)
+
+
+class ListMCPResourceTemplatesTool(Tool):
+    name = "list_mcp_resource_templates"
+    description = (
+        "List MCP resource templates visible in the current execution boundary."
+    )
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "server_name": {
+                "type": "string",
+                "description": "Optional globally available MCP server name filter",
+            }
+        },
+        "required": [],
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **_kwargs: Any) -> str:
+        server_name = args.get("server_name")
+        templates = mcp_service.list_agent_resource_templates(
+            agent,
+            server_name=server_name
+            if isinstance(server_name, str) and server_name.strip()
+            else None,
+        )
+        return json.dumps(templates, ensure_ascii=False)
+
+
+class ReadMCPResourceTool(Tool):
+    name = "read_mcp_resource"
+    description = "Read an MCP resource from a globally available server."
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "server_name": {
+                "type": "string",
+                "description": "Globally available MCP server name",
+            },
+            "uri": {
+                "type": "string",
+                "description": "Target MCP resource URI",
+            },
+        },
+        "required": ["server_name", "uri"],
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **_kwargs: Any) -> str:
+        server_name = args.get("server_name")
+        uri = args.get("uri")
+        if not isinstance(server_name, str) or not server_name.strip():
+            return json.dumps({"error": "server_name is required"})
+        if not isinstance(uri, str) or not uri.strip():
+            return json.dumps({"error": "uri is required"})
+        result = mcp_service.read_agent_resource(
+            agent,
+            server_name=server_name.strip(),
+            uri=uri.strip(),
+        )
+        return json.dumps(result, ensure_ascii=False)
+
+
+class ListMCPPromptsTool(Tool):
+    name = "list_mcp_prompts"
+    description = "List MCP prompts visible in the current execution boundary."
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "server_name": {
+                "type": "string",
+                "description": "Optional globally available MCP server name filter",
+            }
+        },
+        "required": [],
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **_kwargs: Any) -> str:
+        server_name = args.get("server_name")
+        prompts = mcp_service.list_agent_prompts(
+            agent,
+            server_name=server_name
+            if isinstance(server_name, str) and server_name.strip()
+            else None,
+        )
+        return json.dumps(prompts, ensure_ascii=False)
+
+
+class GetMCPPromptTool(Tool):
+    name = "get_mcp_prompt"
+    description = "Get an MCP prompt from a globally available server."
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "server_name": {
+                "type": "string",
+                "description": "Globally available MCP server name",
+            },
+            "name": {
+                "type": "string",
+                "description": "Prompt name",
+            },
+            "arguments": {
+                "type": "object",
+                "description": "Optional prompt arguments",
+            },
+        },
+        "required": ["server_name", "name"],
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **_kwargs: Any) -> str:
+        server_name = args.get("server_name")
+        name = args.get("name")
+        arguments = args.get("arguments")
+        if not isinstance(server_name, str) or not server_name.strip():
+            return json.dumps({"error": "server_name is required"})
+        if not isinstance(name, str) or not name.strip():
+            return json.dumps({"error": "name is required"})
+        if arguments is not None and not isinstance(arguments, dict):
+            return json.dumps({"error": "arguments must be an object"})
+        result = mcp_service.get_agent_prompt(
+            agent,
+            server_name=server_name.strip(),
+            name=name.strip(),
+            arguments=arguments if isinstance(arguments, dict) else None,
+        )
+        return json.dumps(result, ensure_ascii=False)

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

@@ -0,0 +1,152 @@
+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
+
+
+def _append_stream_chunk(
+    buffer: list[str],
+    size: int,
+    text: str,
+    on_output: Callable[[str], None] | None,
+) -> int:
+    if on_output is None or not text:
+        return size
+    buffer.append(text)
+    size += len(text)
+    if size >= 2048:
+        on_output("".join(buffer))
+        buffer.clear()
+        return 0
+    return size
+
+
+def _flush_stream_chunk(
+    buffer: list[str], on_output: Callable[[str], None] | None
+) -> None:
+    if on_output is None or not buffer:
+        return
+    on_output("".join(buffer))
+    buffer.clear()
+
+
+class ReadTool(Tool):
+    name = "read"
+    description = (
+        "Read a file with line numbers, or list a directory. "
+        "Use start_line and end_line to read a specific range (1-indexed, inclusive). "
+        "Line numbers in the output are used as input to the edit tool."
+    )
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "Absolute path to the file or directory to read",
+            },
+            "start_line": {
+                "type": "integer",
+                "description": "First line to read (1-indexed, inclusive). Defaults to 1.",
+            },
+            "end_line": {
+                "type": "integer",
+                "description": "Last line to read (1-indexed, inclusive). Defaults to end of file.",
+            },
+        },
+        "required": ["path"],
+    }
+
+    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")
+
+        if real_path.is_dir():
+            try:
+                entries = []
+                stream_buffer: list[str] = []
+                stream_size = 0
+                for entry in sorted(os.listdir(real_path)):
+                    full = real_path / entry
+                    kind = "dir" if full.is_dir() else "file"
+                    size = full.stat().st_size if kind == "file" else None
+                    entries.append({"name": entry, "type": kind, "size": size})
+                    label = f"{kind}\t{entry}"
+                    if size is not None:
+                        label = f"{label}\t{size}"
+                    stream_size = _append_stream_chunk(
+                        stream_buffer,
+                        stream_size,
+                        f"{label}\n",
+                        on_output,
+                    )
+                _flush_stream_chunk(stream_buffer, on_output)
+                logger.debug(
+                    "Listed directory: {} ({} entries)", path_str, len(entries)
+                )
+                return json.dumps({"path": path_str, "entries": entries})
+            except Exception as e:
+                re_raise_interrupt(agent, e)
+                return json.dumps({"error": str(e)})
+
+        if real_path.is_file():
+            try:
+                with open(real_path, encoding="utf-8") as f:
+                    total_lines = sum(1 for _ in f)
+
+                start = max(1, int(args.get("start_line", 1)))
+                end = min(total_lines, int(args.get("end_line", total_lines)))
+                width = max(6, len(str(total_lines)))
+                selected_parts: list[str] = []
+                stream_buffer = []
+                stream_size = 0
+
+                with open(real_path, encoding="utf-8") as f:
+                    for line_number, line in enumerate(f, start=1):
+                        if line_number < start:
+                            continue
+                        if line_number > end:
+                            break
+                        numbered_line = f"{line_number:{width}d}\t{line}"
+                        selected_parts.append(numbered_line)
+                        stream_size = _append_stream_chunk(
+                            stream_buffer,
+                            stream_size,
+                            numbered_line,
+                            on_output,
+                        )
+
+                _flush_stream_chunk(stream_buffer, on_output)
+                numbered = "".join(selected_parts)
+
+                logger.debug(
+                    "Read file: {} (lines {}-{} of {})",
+                    path_str,
+                    start,
+                    end,
+                    total_lines,
+                )
+                return json.dumps(
+                    {
+                        "path": path_str,
+                        "total_lines": total_lines,
+                        "start_line": start,
+                        "end_line": end,
+                        "content": numbered,
+                    }
+                )
+            except Exception as e:
+                re_raise_interrupt(agent, e)
+                return json.dumps({"error": str(e)})
+
+        return json.dumps({"error": f"Not found: {path_str}"})

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

@@ -0,0 +1,50 @@
+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 SendTool(Tool):
+    name = "send"
+    description = "Send a formal message to one current contact."
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "target": {
+                "type": "string",
+                "description": "One target id, name, or unique short id from contacts.",
+            },
+            "parts": {
+                "type": "array",
+                "description": "Ordered message parts to send.",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "type": {"type": "string", "enum": ["text", "image"]},
+                        "text": {"type": "string"},
+                        "asset_id": {"type": "string"},
+                        "mime_type": {"type": "string"},
+                        "width": {"type": "integer"},
+                        "height": {"type": "integer"},
+                        "alt": {"type": "string"},
+                    },
+                    "required": ["type"],
+                },
+            },
+        },
+        "required": ["target", "parts"],
+        "additionalProperties": False,
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **_kwargs: Any) -> str:
+        target = args.get("target")
+        if not isinstance(target, str) or not target.strip():
+            raise ValueError("send.target must be a non-empty string")
+        return agent.send_message(
+            target_ref=target.strip(),
+            raw_parts=args.get("parts"),
+        )

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

@@ -0,0 +1,84 @@
+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 SetPermissionsTool(Tool):
+    name = "set_permissions"
+    description = (
+        "Update a workflow's permission boundary by patching its bound Leader's "
+        "allow_network and write_dirs."
+    )
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "workflow_id": {
+                "type": "string",
+                "description": "ID of the workflow whose permission boundary should be updated",
+            },
+            "allow_network": {
+                "type": "boolean",
+                "description": "Optional patched network permission for the workflow boundary",
+            },
+            "write_dirs": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Optional patched writable directory boundary for the workflow",
+            },
+        },
+        "required": ["workflow_id"],
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **_kwargs: Any) -> str:
+        from flowent.graph_service import set_tab_permissions
+        from flowent.settings import (
+            build_assistant_allow_network,
+            build_assistant_write_dirs,
+        )
+
+        workflow_id = args.get("workflow_id")
+        raw_allow_network = args.get("allow_network")
+        raw_write_dirs = args.get("write_dirs")
+
+        if not isinstance(workflow_id, str) or not workflow_id.strip():
+            return json.dumps({"error": "workflow_id must be a non-empty string"})
+
+        allow_network: bool | None = None
+        if "allow_network" in args:
+            try:
+                allow_network = build_assistant_allow_network(
+                    raw_allow_network,
+                    field_name="allow_network",
+                )
+            except ValueError as exc:
+                return json.dumps({"error": str(exc)})
+
+        write_dirs: list[str] | None = None
+        if "write_dirs" in args:
+            try:
+                write_dirs = build_assistant_write_dirs(
+                    raw_write_dirs,
+                    field_name="write_dirs",
+                )
+            except ValueError as exc:
+                return json.dumps({"error": str(exc)})
+
+        result, error = set_tab_permissions(
+            tab_id=workflow_id.strip(),
+            allow_network=allow_network,
+            write_dirs=write_dirs,
+            caller_allow_network=agent.config.allow_network,
+            caller_write_dirs=list(agent.config.write_dirs),
+            actor_id=agent.uuid,
+        )
+        if error is not None or result is None:
+            return json.dumps(
+                {"error": error or "Failed to update workflow permissions"}
+            )
+        return json.dumps(result)

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

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import json
+from math import isfinite
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from flowent.tools import Tool
+
+if TYPE_CHECKING:
+    from flowent.agent import Agent
+
+
+class SleepTool(Tool):
+    name = "sleep"
+    description = (
+        "Enter a timed wait that resumes on whichever happens first: a new input "
+        "arrives or the requested duration elapses. Use this when you want to wait "
+        "until a deadline without missing messages."
+    )
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "seconds": {
+                "type": "number",
+                "description": "How many seconds to wait before resuming execution. Supports fractional seconds.",
+                "minimum": 0,
+            }
+        },
+        "required": ["seconds"],
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **_kwargs: Any) -> str:
+        seconds = args.get("seconds")
+        if isinstance(seconds, bool) or not isinstance(seconds, int | float):
+            return json.dumps({"error": "seconds must be a non-negative number"})
+
+        duration = float(seconds)
+        if not isfinite(duration) or duration < 0:
+            return json.dumps({"error": "seconds must be a non-negative number"})
+
+        return agent.request_sleep(seconds=duration)

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

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from flowent.events import event_bus
+from flowent.models import Event, EventType, TodoItem
+from flowent.tools import Tool
+
+if TYPE_CHECKING:
+    from flowent.agent import Agent
+
+
+class TodoTool(Tool):
+    name = "todo"
+    description = "Replace the full todo list with a new ordered list of task strings."
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "todos": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Complete replacement todo list. Pass an empty array to clear all todos.",
+            },
+        },
+        "required": ["todos"],
+    }
+
+    def execute(self, agent: Agent, args: dict[str, Any], **_kwargs: Any) -> str:
+        raw_todos = args["todos"]
+        if not isinstance(raw_todos, list) or not all(
+            isinstance(item, str) for item in raw_todos
+        ):
+            return json.dumps({"error": "todos must be an array of strings"})
+
+        next_todos = [TodoItem(text=item) for item in raw_todos]
+        agent.set_todos(next_todos)
+        self._emit_todo_event(agent)
+        return json.dumps({"status": "updated"})
+
+    @staticmethod
+    def _emit_todo_event(agent: Agent) -> None:
+        event_bus.emit(
+            Event(
+                type=EventType.NODE_TODOS_CHANGED,
+                agent_id=agent.uuid,
+                data={
+                    "todos": [t.serialize() for t in agent.get_todos_snapshot()],
+                },
+            ),
+        )