modus-ai 0.1.0__tar.gz

modus_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Modus Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

modus_ai-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include LICENSE
+include README.md
+prune tests
+prune yma
+prune site
+prune sample_projects
+prune docs
+prune assets
+global-exclude *.py[cod]
+global-exclude __pycache__/*

modus_ai-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: modus-ai
+Version: 0.1.0
+Summary: Modular AI agent framework
+Author: Modus Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ModusAgent/modus
+Project-URL: Repository, https://github.com/ModusAgent/modus
+Project-URL: Documentation, https://github.com/ModusAgent/modus#readme
+Keywords: ai,agents,llm,framework,memory,mcp,orchestration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.120.2
+Requires-Dist: openai>=2.50.0
+Requires-Dist: lancedb>=0.12.0
+Requires-Dist: pyarrow>=15.0.0
+Requires-Dist: mcp>=2.0.0
+Requires-Dist: fastapi>=0.141.1
+Requires-Dist: uvicorn>=0.52.0
+Requires-Dist: apscheduler>=3.11.3
+Requires-Dist: pillow>=12.3.0
+Requires-Dist: google-genai>=2.16.0
+Requires-Dist: pyyaml>=6.0.3
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/images/logo-dark-readme.png" alt="Modus" width="200">
+  <br><br>
+  <b>Modus — Modular AI agents. Composable by design.</b><br><br>
+    <img src="https://img.shields.io/badge/status-alpha-8B5CF6?style=for-the-badge" alt="Status">
+    <img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python">
+    <img src="https://img.shields.io/badge/tests-231%20passing-22C55E?style=for-the-badge" alt="Tests">
+    <img src="https://img.shields.io/badge/license-MIT-blue?style=for-the-badge" alt="MIT">
+  <br><br>
+  <b>Modus</b> is an open-source modular AI agent framework that provides reusable components<br>
+  for building, orchestrating, and deploying autonomous AI systems.<br><br>
+  Memory systems. Planning loops. Safety guards. Tool execution. MCP integration.<br>
+  All packaged as swappable modules with clear protocol boundaries.<br><br>
+  <a href="docs/index.md"><img src="https://img.shields.io/badge/Docs-8B5CF6?style=for-the-badge" alt="Docs"></a>
+  <a href="docs/modules/memory.md"><img src="https://img.shields.io/badge/Memory-22C55E?style=for-the-badge" alt="Memory"></a>
+  <a href="docs/guide/actions.md"><img src="https://img.shields.io/badge/Actions-3B82F6?style=for-the-badge" alt="Actions"></a>
+  <a href="docs/roadmap.md"><img src="https://img.shields.io/badge/Roadmap-F59E0B?style=for-the-badge" alt="Roadmap"></a>
+</p>
+
+## Why Modus?
+
+Building AI agents today means reinventing the same infrastructure every time: memory systems, planning loops, safety guards, tool execution, perception pipelines. Every framework forces you into a monolithic agent runtime where swapping one piece means rewriting half the system.
+
+Modus takes the opposite approach.
+
+Each capability is a self-contained module with a well-defined protocol interface. Swap memory backends without touching the planner. Change planning strategies without rewriting the action layer. Add safety policies without forking the codebase.
+
+No vendor lock-in. No monolithic runtimes. Just composable building blocks.
+
+## Quick start
+
+```bash
+pip install modus-ai
+```
+
+```python
+from modus import Agent
+from modus.memory import Memory
+from modus.memory.analysis.embeddings import OpenAIEmbedding
+
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant.",
+    provider="openai",
+    memory=Memory("./data", embedding=OpenAIEmbedding()),
+)
+
+# Memory context auto-injected, Chat auto-managed
+response = agent.run("What do I know about Project Phoenix?")
+```
+
+## What's built
+
+| Module | Features | Status |
+|---|---|---|
+| **Agent** | ReAct loop, Chat history, Memory injection, Tool calling, Event hooks | ✅ |
+| **Memory** | OKF `.md` files, FTS5 keyword search, LanceDB vector search, Hybrid scoring, LLM analysis, entity extraction, TTL/eviction, Dreaming, consolidation, tenant isolation, concurrent writes | ✅ |
+| **Actions** | Local tool registry, `@tool` decorator, MCP stdio/HTTP transport, argument validation, result compaction, caching, retry, timeout | ✅ |
+| **Orchestration** | Workflow graph engine, dependency resolution, conditional routing, loops, HITL, state persistence, validation, hooks, async, sub-workflows, Mermaid export, context isolation | ✅ |
+| **Deploy** | FastAPI webhook server, APScheduler (cron + interval) | ✅ |
+| **Providers** | OpenAI + Anthropic with tool-call support, provider-agnostic protocol | ✅ |
+
+## Key architecture
+
+- **Monorepo, single package:** `pip install modus-ai`
+- **Memory:** OKF `.md` files + YAML frontmatter → FTS5 + LanceDB hybrid search
+- **Actions:** Plugin local tools or connect MCP servers (`stdio` or `HTTP`)
+- **ReAct loop:** Agent detects LLM tool calls, executes in parallel, feeds results back
+- **Chat:** Token-budget conversation history, auto-summarized overflow
+- **All modules are standalone:** `from modus.memory import Memory` — works without Agent
+
+## Example: Tools
+
+```python
+from modus import Agent
+from modus.actions import tool
+
+@tool(name="get_weather", description="Get weather for a city", parameters={
+    "type": "object",
+    "properties": {"city": {"type": "string"}},
+    "required": ["city"],
+})
+def get_weather(city: str) -> str:
+    return f"Sunny, 25°C in {city}"
+
+agent = Agent(name="WeatherBot", instructions="Use tools to answer questions.")
+agent.actions.register(get_weather)
+
+response = agent.run("What is the weather in Tokyo?")
+```
+
+## Example: MCP server
+
+```python
+agent.actions.connect(
+    "filesystem",
+    command="npx",
+    args=["-y", "@modelcontextprotocol/server-filesystem", "."],
+)
+# Tools auto-discovered and available in the ReAct loop
+```
+
+## Example: Workflow with multiple agents
+
+```python
+from modus.orchestration import Workflow, Step
+
+workflow = Workflow(steps={
+    "classify": Step(agent=classifier, next={"billing": "resolve", "tech": "escalate"}),
+    "resolve": Step(agent=resolver, retry=2, timeout=30),
+    "respond": Step(agent=responder, depends_on=["resolve", "escalate"]),
+})
+
+result = workflow.run("I was charged twice")
+```
+
+## Documentation
+
+| Section | Description |
+|---|---|
+| [Architecture](docs/architecture.md) | Block architecture and lifecycle |
+| [Memory Guide](docs/modules/memory.md) | OKF concepts, storage, retrieval, API reference |
+| [Actions Guide](docs/guide/actions.md) | MCP servers, tool execution, ReAct loop |
+| [Protocol Reference](docs/reference/protocols.md) | Module interface contracts |
+| [Contributing](docs/contributing.md) | Development guide and RFC process |
+| [Roadmap](docs/roadmap.md) | Upcoming milestones |
+
+## Current status
+
+**Alpha.** Agent, memory, actions, safety, planner, vision, skills, providers,
+orchestration, and deploy are implemented and tested (280 tests).
+
+## License
+
+MIT

modus_ai-0.1.0/README.md

@@ -0,0 +1,135 @@
+<p align="center">
+  <img src="assets/images/logo-dark-readme.png" alt="Modus" width="200">
+  <br><br>
+  <b>Modus — Modular AI agents. Composable by design.</b><br><br>
+    <img src="https://img.shields.io/badge/status-alpha-8B5CF6?style=for-the-badge" alt="Status">
+    <img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python">
+    <img src="https://img.shields.io/badge/tests-231%20passing-22C55E?style=for-the-badge" alt="Tests">
+    <img src="https://img.shields.io/badge/license-MIT-blue?style=for-the-badge" alt="MIT">
+  <br><br>
+  <b>Modus</b> is an open-source modular AI agent framework that provides reusable components<br>
+  for building, orchestrating, and deploying autonomous AI systems.<br><br>
+  Memory systems. Planning loops. Safety guards. Tool execution. MCP integration.<br>
+  All packaged as swappable modules with clear protocol boundaries.<br><br>
+  <a href="docs/index.md"><img src="https://img.shields.io/badge/Docs-8B5CF6?style=for-the-badge" alt="Docs"></a>
+  <a href="docs/modules/memory.md"><img src="https://img.shields.io/badge/Memory-22C55E?style=for-the-badge" alt="Memory"></a>
+  <a href="docs/guide/actions.md"><img src="https://img.shields.io/badge/Actions-3B82F6?style=for-the-badge" alt="Actions"></a>
+  <a href="docs/roadmap.md"><img src="https://img.shields.io/badge/Roadmap-F59E0B?style=for-the-badge" alt="Roadmap"></a>
+</p>
+
+## Why Modus?
+
+Building AI agents today means reinventing the same infrastructure every time: memory systems, planning loops, safety guards, tool execution, perception pipelines. Every framework forces you into a monolithic agent runtime where swapping one piece means rewriting half the system.
+
+Modus takes the opposite approach.
+
+Each capability is a self-contained module with a well-defined protocol interface. Swap memory backends without touching the planner. Change planning strategies without rewriting the action layer. Add safety policies without forking the codebase.
+
+No vendor lock-in. No monolithic runtimes. Just composable building blocks.
+
+## Quick start
+
+```bash
+pip install modus-ai
+```
+
+```python
+from modus import Agent
+from modus.memory import Memory
+from modus.memory.analysis.embeddings import OpenAIEmbedding
+
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant.",
+    provider="openai",
+    memory=Memory("./data", embedding=OpenAIEmbedding()),
+)
+
+# Memory context auto-injected, Chat auto-managed
+response = agent.run("What do I know about Project Phoenix?")
+```
+
+## What's built
+
+| Module | Features | Status |
+|---|---|---|
+| **Agent** | ReAct loop, Chat history, Memory injection, Tool calling, Event hooks | ✅ |
+| **Memory** | OKF `.md` files, FTS5 keyword search, LanceDB vector search, Hybrid scoring, LLM analysis, entity extraction, TTL/eviction, Dreaming, consolidation, tenant isolation, concurrent writes | ✅ |
+| **Actions** | Local tool registry, `@tool` decorator, MCP stdio/HTTP transport, argument validation, result compaction, caching, retry, timeout | ✅ |
+| **Orchestration** | Workflow graph engine, dependency resolution, conditional routing, loops, HITL, state persistence, validation, hooks, async, sub-workflows, Mermaid export, context isolation | ✅ |
+| **Deploy** | FastAPI webhook server, APScheduler (cron + interval) | ✅ |
+| **Providers** | OpenAI + Anthropic with tool-call support, provider-agnostic protocol | ✅ |
+
+## Key architecture
+
+- **Monorepo, single package:** `pip install modus-ai`
+- **Memory:** OKF `.md` files + YAML frontmatter → FTS5 + LanceDB hybrid search
+- **Actions:** Plugin local tools or connect MCP servers (`stdio` or `HTTP`)
+- **ReAct loop:** Agent detects LLM tool calls, executes in parallel, feeds results back
+- **Chat:** Token-budget conversation history, auto-summarized overflow
+- **All modules are standalone:** `from modus.memory import Memory` — works without Agent
+
+## Example: Tools
+
+```python
+from modus import Agent
+from modus.actions import tool
+
+@tool(name="get_weather", description="Get weather for a city", parameters={
+    "type": "object",
+    "properties": {"city": {"type": "string"}},
+    "required": ["city"],
+})
+def get_weather(city: str) -> str:
+    return f"Sunny, 25°C in {city}"
+
+agent = Agent(name="WeatherBot", instructions="Use tools to answer questions.")
+agent.actions.register(get_weather)
+
+response = agent.run("What is the weather in Tokyo?")
+```
+
+## Example: MCP server
+
+```python
+agent.actions.connect(
+    "filesystem",
+    command="npx",
+    args=["-y", "@modelcontextprotocol/server-filesystem", "."],
+)
+# Tools auto-discovered and available in the ReAct loop
+```
+
+## Example: Workflow with multiple agents
+
+```python
+from modus.orchestration import Workflow, Step
+
+workflow = Workflow(steps={
+    "classify": Step(agent=classifier, next={"billing": "resolve", "tech": "escalate"}),
+    "resolve": Step(agent=resolver, retry=2, timeout=30),
+    "respond": Step(agent=responder, depends_on=["resolve", "escalate"]),
+})
+
+result = workflow.run("I was charged twice")
+```
+
+## Documentation
+
+| Section | Description |
+|---|---|
+| [Architecture](docs/architecture.md) | Block architecture and lifecycle |
+| [Memory Guide](docs/modules/memory.md) | OKF concepts, storage, retrieval, API reference |
+| [Actions Guide](docs/guide/actions.md) | MCP servers, tool execution, ReAct loop |
+| [Protocol Reference](docs/reference/protocols.md) | Module interface contracts |
+| [Contributing](docs/contributing.md) | Development guide and RFC process |
+| [Roadmap](docs/roadmap.md) | Upcoming milestones |
+
+## Current status
+
+**Alpha.** Agent, memory, actions, safety, planner, vision, skills, providers,
+orchestration, and deploy are implemented and tested (280 tests).
+
+## License
+
+MIT

modus_ai-0.1.0/modus/__init__.py

@@ -0,0 +1,3 @@
+from modus.agent import Agent
+
+__all__ = ["Agent"]

modus_ai-0.1.0/modus/actions/__init__.py

@@ -0,0 +1,12 @@
+from modus.actions.base import Actions
+from modus.actions.local import EchoTool, FunctionTool, tool
+from modus.actions.registry import LocalToolRegistry, ToolRegistry
+
+__all__ = [
+    "Actions",
+    "EchoTool",
+    "FunctionTool",
+    "LocalToolRegistry",
+    "ToolRegistry",
+    "tool",
+]

modus_ai-0.1.0/modus/actions/base.py

@@ -0,0 +1,145 @@
+import hashlib
+import json
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+from modus.actions.compaction import compact_result
+from modus.actions.mcp.client import MCPClientManager
+from modus.actions.registry import ToolRegistry
+from modus.core.protocols import Tool
+from modus.core.types import ToolDefinition
+
+logger = logging.getLogger(__name__)
+
+
+def _validate_args(parameters: dict[str, Any] | None, args: dict[str, Any]) -> None:
+    if not parameters:
+        return
+    required = parameters.get("required", [])
+    missing = [field for field in required if field not in args]
+    if missing:
+        raise ValueError(f"Missing required arguments: {', '.join(missing)}")
+
+
+def _normalize_result(result: Any) -> str:
+    if isinstance(result, str):
+        return result
+    return json.dumps(result, default=str)
+
+
+class Actions:
+    def __init__(
+        self,
+        on_tool_call: Callable[[str, dict[str, Any]], None] | None = None,
+        on_approval: Callable[[str, dict[str, Any]], bool] | None = None,
+    ) -> None:
+        self._registry = ToolRegistry()
+        self._mcp = MCPClientManager()
+        self._cache: dict[str, dict[str, Any]] = {}
+        self._on_tool_call = on_tool_call
+        self._on_approval = on_approval
+        self._middleware: list[Callable] = []
+
+    def use(self, middleware_fn: Callable) -> None:
+        self._middleware.append(middleware_fn)
+
+    def register(self, tool: Tool) -> None:
+        self._registry.register(tool)
+
+    def connect(
+        self,
+        server: str,
+        *,
+        command: str | None = None,
+        args: list[str] | None = None,
+        url: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._mcp.connect(
+            server,
+            command=command,
+            args=args,
+            url=url,
+            **kwargs,
+        )
+
+    def list_tools(self) -> list[ToolDefinition]:
+        tools = self._registry.list_tools()
+        tools.extend(self._mcp.list_tools())
+        return tools
+
+    def to_openai_schemas(self) -> list[dict[str, Any]]:
+        return self._registry.to_openai_schemas()
+
+    def to_anthropic_schemas(self) -> list[dict[str, Any]]:
+        return self._registry.to_anthropic_schemas()
+
+    def execute(
+        self,
+        tool_name: str,
+        args: dict[str, Any],
+        timeout: int = 30,
+        retry: int = 2,
+    ) -> dict[str, Any]:
+        if self._on_tool_call:
+            self._on_tool_call(tool_name, args)
+
+        cache_key = _cache_key(tool_name, args)
+        if cache_key in self._cache:
+            return self._cache[cache_key]
+
+        for attempt in range(retry + 1):
+            try:
+                result = self._execute_once(tool_name, args, timeout)
+                self._cache[cache_key] = result
+                return result
+            except Exception as exc:
+                if attempt == retry:
+                    return {"content": str(exc), "is_error": True}
+                time.sleep(0.5 * (attempt + 1))
+
+        return {"content": "Unexpected error", "is_error": True}
+
+    def _execute_once(self, tool_name: str, args: dict[str, Any], timeout: int) -> dict[str, Any]:
+        if self._registry.has(tool_name):
+            tool = self._registry.get(tool_name)
+
+            # Authorization check
+            require_approval = getattr(tool, "require_approval", False)
+            if require_approval and self._on_approval is not None:
+                approved = self._on_approval(tool_name, args)
+                if not approved:
+                    logger.info("Tool '%s' rejected by approval callback", tool_name)
+                    return {"content": f"Tool '{tool_name}' execution rejected", "is_error": True}
+
+            _validate_args(tool.parameters, args)
+
+            # Middleware chain
+            def call():
+                return tool.execute(**args)
+            for mw in reversed(self._middleware):
+                call = mw(call)
+            raw = call()
+
+            content = compact_result(_normalize_result(raw))
+            return {"content": content, "is_error": False}
+
+        if self._mcp.has_tool(tool_name):
+            raw = self._mcp.execute(tool_name, args, timeout=timeout)
+            content = compact_result(_normalize_result(raw))
+            return {"content": content, "is_error": False}
+
+        return {
+            "content": f"Unknown tool: {tool_name}",
+            "is_error": True,
+        }
+
+    def clear_cache(self) -> None:
+        self._cache.clear()
+
+
+def _cache_key(tool_name: str, args: dict[str, Any]) -> str:
+    raw = f"{tool_name}:{json.dumps(args, sort_keys=True)}"
+    return hashlib.sha256(raw.encode()).hexdigest()

modus_ai-0.1.0/modus/actions/compaction.py

@@ -0,0 +1,12 @@
+def compact_result(
+    content: str,
+    *,
+    max_chars: int = 12_000,
+) -> str:
+    """Shrink oversized tool output before returning it to the LLM."""
+    if len(content) <= max_chars:
+        return content
+    truncated = max_chars - 20
+    truncated = max(truncated, 0)
+    removed = len(content) - truncated
+    return f"{content[:truncated]}\n...[truncated {removed} chars]"

modus_ai-0.1.0/modus/actions/local.py

@@ -0,0 +1,47 @@
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class FunctionTool:
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    _fn: Callable[..., str] = field(repr=False)
+    require_approval: bool = False
+
+    def execute(self, **kwargs: Any) -> str:
+        return self._fn(**kwargs)
+
+
+def tool(
+    name: str,
+    description: str,
+    parameters: dict[str, Any],
+    require_approval: bool = False,
+) -> Callable[[Callable[..., str]], FunctionTool]:
+    def decorator(fn: Callable[..., str]) -> FunctionTool:
+        return FunctionTool(
+            name=name,
+            description=description,
+            parameters=parameters,
+            require_approval=require_approval,
+            _fn=fn,
+        )
+
+    return decorator
+
+
+class EchoTool:
+    name = "echo"
+    description = "Echo back the input message"
+    parameters = {
+        "type": "object",
+        "properties": {"message": {"type": "string"}},
+        "required": ["message"],
+    }
+    require_approval = False
+
+    def execute(self, *, message: str) -> str:
+        return message

modus_ai-0.1.0/modus/actions/mcp/__init__.py

@@ -0,0 +1,3 @@
+from modus.actions.mcp.client import MCPClientManager
+
+__all__ = ["MCPClientManager"]

modus_ai-0.1.0/modus/actions/mcp/_stdio.py

@@ -0,0 +1,79 @@
+import json
+import logging
+import subprocess
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class MCPStdioServer:
+    def __init__(self, command: str, args: list[str] | None = None) -> None:
+        self._command = command
+        self._args = args or []
+        self._process: subprocess.Popen | None = None
+
+    def start(self) -> None:
+        self._process = subprocess.Popen(
+            [self._command, *self._args],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+
+    def send(self, request: dict[str, Any]) -> dict[str, Any]:
+        if self._process is None or self._process.stdin is None:
+            raise RuntimeError("Server not started")
+        line = json.dumps(request) + "\n"
+        self._process.stdin.write(line)
+        self._process.stdin.flush()
+        raw = self._process.stdout.readline() if self._process.stdout else ""
+        if not raw:
+            raise ConnectionError("MCP server closed connection")
+        return json.loads(raw)
+
+    def close(self) -> None:
+        if self._process:
+            self._process.terminate()
+            self._process.wait(timeout=5)
+
+    def list_tools(self) -> list[dict[str, Any]]:
+        resp = self.send({"jsonrpc": "2.0", "method": "tools/list", "id": 1})
+        return resp.get("result", {}).get("tools", [])
+
+    def call_tool(self, name: str, args: dict[str, Any], timeout: int = 30) -> str:
+        if self._process is None or self._process.stdout is None:
+            raise RuntimeError("Server not started")
+        request = json.dumps({
+            "jsonrpc": "2.0",
+            "method": "tools/call",
+            "params": {"name": name, "arguments": args},
+            "id": 2,
+        }) + "\n"
+        self._process.stdin.write(request)
+        self._process.stdin.flush()
+        try:
+            self._process.stdout.flush()
+        except Exception:
+            logger.debug("Failed to flush stdout stream")
+        raw = self._read_line_with_timeout(timeout)
+        if not raw:
+            self.close()
+            raise TimeoutError(f"Tool '{name}' timed out after {timeout}s")
+        resp = json.loads(raw)
+        result = resp.get("result", {})
+        content = result.get("content", [])
+        parts = [c.get("text", "") for c in content if c.get("type") == "text"]
+        return "\n".join(parts)
+
+    def _read_line_with_timeout(self, timeout: int) -> str:
+        import select
+        if self._process is None or self._process.stdout is None:
+            return ""
+        import time
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            r, _, _ = select.select([self._process.stdout], [], [], 1.0)
+            if r:
+                return self._process.stdout.readline()
+        return ""