wolf-agent 0.1.0__tar.gz

wolf_agent-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.DS_Store
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.coverage
+htmlcov/
+.wolfsuite/
+.commercial-integration/
+# Cargo workspace build output (root Cargo.toml); maturin gates write here.
+/target/

wolf_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wolfgang Schoenberger
+
+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.

wolf_agent-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.5
+Name: wolf-agent
+Version: 0.1.0
+Summary: Python client for the wolf mcp server: offline Office document tools for AI agents
+Project-URL: Homepage, https://wolfsdk.com
+Project-URL: Documentation, https://wolfsdk.com/runtime/docs#integrations
+Author: Wolfgang Schoenberger
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,docx,mcp,model-context-protocol,office,pdf,pptx,xlsx
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Office Suites
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# wolf-agent (Python)
+
+A thin client for the `wolf mcp` stdio server. `wolf` itself is a native executable: it needs no
+Python, no pip packages and no network. This client uses only the Python standard library
+(Python 3.11 or newer), opens no sockets, and holds no tool logic: it spawns
+`wolf mcp --workspace-root ROOT`, speaks newline-delimited JSON-RPC 2.0 (`initialize`,
+`notifications/initialized`, `tools/list`, `tools/call`), and stops the child on close.
+
+## Install
+
+```sh
+pip install wolf-agent
+```
+
+The `wolf` executable ships with Wolf Runtime. Start a free evaluation at
+<https://wolfxl.com/evaluate>, then run `wolf mcp --help` to check that your build includes the
+server. MCP clients that launch servers by command can also run `wolf mcp --workspace-root ROOT`
+directly, without this package.
+
+## Use
+
+```python
+from wolf_agent import WolfAgentClient, ToolError
+
+with WolfAgentClient("/abs/workspace", wolf="/path/to/wolf") as wolf:
+    read = wolf.read("report.docx")  # revision_sha256, html, blocks
+    hits = wolf.search("report.docx", "Quarterly")  # anchored matches
+    old = hits["matches"][0]["html"]
+    try:
+        receipt = wolf.edit(
+            "report.docx",
+            read["revision_sha256"],
+            "revised",
+            [{"old_html": old, "new_html": old.replace("Quarterly", "Annual")}],
+            approved=True,
+        )
+    except ToolError as refusal:  # isError: typed refusal
+        print(refusal.code, refusal.hint)
+    else:
+        print(receipt["status"], receipt["published"])
+```
+
+`wolf_observe`, `wolf_transact` and `wolf_diff` take the native agent request directly
+(`wolf.wolf_observe(request)`); `wolf.lifecycle(phase, transaction, approved=None)` continues a
+server-owned transaction (`lifecycle_plan` through `lifecycle_discard`; commit needs
+`approved=True`); `call_tool(name, arguments)` reaches any tool and `list_tools()` returns the
+server's descriptors. Each result is the tool's `structuredContent`.
+
+## Behaviour
+
+| Condition | Result |
+|---|---|
+| Tool result with `isError` | `ToolError` with `.tool`, `.code`, `.hint`, `.document`; the session stays usable |
+| JSON-RPC error object | `RpcError` with `.code`, `.message`, `.data`; the session stays usable |
+| Non-JSON line, wrong response id, malformed result | `ProtocolError`; the child is stopped and later calls re-raise it |
+| No response within `request_timeout` (default 120 s; `startup_timeout` 30 s) | `WolfTimeoutError`; the child is stopped |
+| Spawn failure, exit or closed pipes | `WolfProcessError` with `.returncode` and the stderr tail |
+
+`close()` (and leaving the `with` block) closes stdin, waits `shutdown_timeout` (5 s), then
+terminates, then kills. `wolf` may also be an argv prefix, for example
+`["docker", "run", "-i", "--rm", "--network", "none", ...]`; `env` replaces the child's whole
+environment.
+
+## Tests
+
+```sh
+python3 -m pytest tests
+```
+
+The tests drive a scripted stand-in server and need only `pytest`.

wolf_agent-0.1.0/README.md

@@ -0,0 +1,70 @@
+# wolf-agent (Python)
+
+A thin client for the `wolf mcp` stdio server. `wolf` itself is a native executable: it needs no
+Python, no pip packages and no network. This client uses only the Python standard library
+(Python 3.11 or newer), opens no sockets, and holds no tool logic: it spawns
+`wolf mcp --workspace-root ROOT`, speaks newline-delimited JSON-RPC 2.0 (`initialize`,
+`notifications/initialized`, `tools/list`, `tools/call`), and stops the child on close.
+
+## Install
+
+```sh
+pip install wolf-agent
+```
+
+The `wolf` executable ships with Wolf Runtime. Start a free evaluation at
+<https://wolfxl.com/evaluate>, then run `wolf mcp --help` to check that your build includes the
+server. MCP clients that launch servers by command can also run `wolf mcp --workspace-root ROOT`
+directly, without this package.
+
+## Use
+
+```python
+from wolf_agent import WolfAgentClient, ToolError
+
+with WolfAgentClient("/abs/workspace", wolf="/path/to/wolf") as wolf:
+    read = wolf.read("report.docx")  # revision_sha256, html, blocks
+    hits = wolf.search("report.docx", "Quarterly")  # anchored matches
+    old = hits["matches"][0]["html"]
+    try:
+        receipt = wolf.edit(
+            "report.docx",
+            read["revision_sha256"],
+            "revised",
+            [{"old_html": old, "new_html": old.replace("Quarterly", "Annual")}],
+            approved=True,
+        )
+    except ToolError as refusal:  # isError: typed refusal
+        print(refusal.code, refusal.hint)
+    else:
+        print(receipt["status"], receipt["published"])
+```
+
+`wolf_observe`, `wolf_transact` and `wolf_diff` take the native agent request directly
+(`wolf.wolf_observe(request)`); `wolf.lifecycle(phase, transaction, approved=None)` continues a
+server-owned transaction (`lifecycle_plan` through `lifecycle_discard`; commit needs
+`approved=True`); `call_tool(name, arguments)` reaches any tool and `list_tools()` returns the
+server's descriptors. Each result is the tool's `structuredContent`.
+
+## Behaviour
+
+| Condition | Result |
+|---|---|
+| Tool result with `isError` | `ToolError` with `.tool`, `.code`, `.hint`, `.document`; the session stays usable |
+| JSON-RPC error object | `RpcError` with `.code`, `.message`, `.data`; the session stays usable |
+| Non-JSON line, wrong response id, malformed result | `ProtocolError`; the child is stopped and later calls re-raise it |
+| No response within `request_timeout` (default 120 s; `startup_timeout` 30 s) | `WolfTimeoutError`; the child is stopped |
+| Spawn failure, exit or closed pipes | `WolfProcessError` with `.returncode` and the stderr tail |
+
+`close()` (and leaving the `with` block) closes stdin, waits `shutdown_timeout` (5 s), then
+terminates, then kills. `wolf` may also be an argv prefix, for example
+`["docker", "run", "-i", "--rm", "--network", "none", ...]`; `env` replaces the child's whole
+environment.
+
+## Tests
+
+```sh
+python3 -m pytest tests
+```
+
+The tests drive a scripted stand-in server and need only `pytest`.

wolf_agent-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "wolf-agent"
+version = "0.1.0"
+description = "Python client for the wolf mcp server: offline Office document tools for AI agents"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Wolfgang Schoenberger" }]
+keywords = ["mcp", "model-context-protocol", "agents", "docx", "xlsx", "pptx", "pdf", "office"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Office/Business :: Office Suites",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://wolfsdk.com"
+Documentation = "https://wolfsdk.com/runtime/docs#integrations"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wolf_agent"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+pythonpath = ["src"]

wolf_agent-0.1.0/src/wolf_agent/__init__.py

@@ -0,0 +1,25 @@
+"""Thin Python client for the ``wolf mcp`` stdio server."""
+
+from .client import CLIENT_VERSION, PROTOCOL_VERSION, WolfAgentClient
+from .errors import (
+    ProtocolError,
+    RpcError,
+    ToolError,
+    WolfAgentError,
+    WolfProcessError,
+    WolfTimeoutError,
+)
+
+__version__ = CLIENT_VERSION
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "ProtocolError",
+    "RpcError",
+    "ToolError",
+    "WolfAgentClient",
+    "WolfAgentError",
+    "WolfProcessError",
+    "WolfTimeoutError",
+    "__version__",
+]

wolf_agent-0.1.0/src/wolf_agent/client.py

@@ -0,0 +1,462 @@
+"""Thin stdio MCP client for ``wolf mcp``.
+
+The client spawns ``wolf mcp --workspace-root ROOT``, speaks newline-delimited JSON-RPC 2.0
+over the child's pipes (``initialize``, ``tools/list``, ``tools/call``), and stops the child
+on close. It owns no tool logic: every tool argument and result is the server's own.
+"""
+
+from __future__ import annotations
+
+import collections
+import contextlib
+import json
+import os
+import queue
+import signal
+import subprocess
+import threading
+import time
+from collections.abc import Mapping, Sequence
+from types import TracebackType
+from typing import Any
+
+from .errors import (
+    ProtocolError,
+    RpcError,
+    ToolError,
+    WolfAgentError,
+    WolfProcessError,
+    WolfTimeoutError,
+)
+
+PROTOCOL_VERSION = "2025-06-18"
+CLIENT_NAME = "wolf-agent-py"
+CLIENT_VERSION = "0.1.0"
+# Receipts are bounded to sixteen MiB by the server; leave room for JSON framing.
+MAX_MESSAGE_BYTES = 32 * 1024 * 1024
+STDERR_TAIL_BYTES = 16 * 1024
+MAX_LIST_PAGES = 64
+
+_EOF = object()
+
+
+def _command(wolf: str | os.PathLike[str] | Sequence[str]) -> list[str]:
+    if isinstance(wolf, (str, os.PathLike)):
+        return [os.fspath(wolf)]
+    command = [os.fspath(part) for part in wolf]
+    if not command:
+        raise ValueError("wolf must name an executable")
+    return command
+
+
+class WolfAgentClient:
+    """One ``wolf mcp`` child process and its MCP session.
+
+    Use it as a context manager. ``wolf`` is the executable (or an argv prefix such as
+    ``["python3", "server.py"]``); ``mcp --workspace-root ROOT`` is appended. ``env`` replaces
+    the child's whole environment when given. ``request_timeout`` bounds every wait for a
+    response; on expiry the process is stopped and :class:`WolfTimeoutError` is raised,
+    because the stream position is no longer known.
+    """
+
+    def __init__(
+        self,
+        workspace_root: str | os.PathLike[str],
+        *,
+        wolf: str | os.PathLike[str] | Sequence[str] = "wolf",
+        env: Mapping[str, str] | None = None,
+        startup_timeout: float = 30.0,
+        request_timeout: float = 120.0,
+        shutdown_timeout: float = 5.0,
+    ) -> None:
+        for name, value in (
+            ("startup_timeout", startup_timeout),
+            ("request_timeout", request_timeout),
+            ("shutdown_timeout", shutdown_timeout),
+        ):
+            if not value > 0:
+                raise ValueError(f"{name} must be positive")
+        root = os.path.abspath(os.fspath(workspace_root))
+        if not os.path.isdir(root):
+            raise ValueError(f"workspace_root is not a directory: {root}")
+        self.workspace_root = root
+        self._argv = [*_command(wolf), "mcp", "--workspace-root", root]
+        self._env = dict(env) if env is not None else None
+        self._startup_timeout = float(startup_timeout)
+        self._request_timeout = float(request_timeout)
+        self._shutdown_timeout = float(shutdown_timeout)
+        self._proc: subprocess.Popen[bytes] | None = None
+        self._lines: queue.Queue[Any] = queue.Queue()
+        self._threads: list[threading.Thread] = []
+        self._stderr: collections.deque[bytes] = collections.deque()
+        self._stderr_size = 0
+        self._stderr_lock = threading.Lock()
+        self._call_lock = threading.Lock()
+        self._next_id = 0
+        self._failure: WolfAgentError | None = None
+        self._closed = False
+        self.protocol_version: str | None = None
+        self.server_info: dict[str, Any] = {}
+        self.instructions: str | None = None
+
+    # ---- lifecycle ---------------------------------------------------------------------
+
+    def __enter__(self) -> WolfAgentClient:
+        self.start()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    @property
+    def returncode(self) -> int | None:
+        """The child's exit status once it has exited, else ``None``."""
+        return None if self._proc is None else self._proc.poll()
+
+    def start(self) -> dict[str, Any]:
+        """Spawn the server and complete the MCP handshake; return the initialize result."""
+        if self._proc is not None or self._closed:
+            raise WolfAgentError("The client was already started.")
+        try:
+            self._proc = subprocess.Popen(
+                self._argv,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                env=self._env,
+                cwd=self.workspace_root,
+                # One group per server: a stop signal also reaches any helper process the
+                # native server started (render engines), so none outlives the client.
+                start_new_session=os.name == "posix",
+            )
+        except OSError as error:
+            self._closed = True
+            raise WolfProcessError(f"Cannot start {self._argv[0]!r}: {error}") from error
+        assert self._proc.stdout is not None and self._proc.stderr is not None
+        self._threads = [
+            threading.Thread(target=self._pump_stdout, args=(self._proc.stdout,), daemon=True),
+            threading.Thread(target=self._pump_stderr, args=(self._proc.stderr,), daemon=True),
+        ]
+        for thread in self._threads:
+            thread.start()
+        try:
+            result = self._request(
+                "initialize",
+                {
+                    "protocolVersion": PROTOCOL_VERSION,
+                    "capabilities": {},
+                    "clientInfo": {"name": CLIENT_NAME, "version": CLIENT_VERSION},
+                },
+                self._startup_timeout,
+            )
+            version = result.get("protocolVersion")
+            if not isinstance(version, str) or not version:
+                raise self._fail(ProtocolError("initialize result has no protocolVersion."))
+            if not isinstance(result.get("capabilities"), dict):
+                raise self._fail(ProtocolError("initialize result has no capabilities object."))
+            info = result.get("serverInfo")
+            instructions = result.get("instructions")
+            self.protocol_version = version
+            self.server_info = info if isinstance(info, dict) else {}
+            self.instructions = instructions if isinstance(instructions, str) else None
+            self._send({"jsonrpc": "2.0", "method": "notifications/initialized"})
+        except BaseException:
+            self.close()
+            raise
+        return result
+
+    def close(self) -> None:
+        """Stop the child: close stdin, wait, then terminate, then kill. Idempotent."""
+        self._closed = True
+        proc = self._proc
+        if proc is None:
+            return
+        deadline = self._shutdown_timeout
+        try:
+            if proc.stdin is not None:
+                with contextlib.suppress(OSError):
+                    proc.stdin.close()
+            try:
+                proc.wait(timeout=deadline)
+            except subprocess.TimeoutExpired:
+                self._stop(force=False)
+                try:
+                    proc.wait(timeout=deadline)
+                except subprocess.TimeoutExpired:
+                    self._stop(force=True)
+                    proc.wait()
+        finally:
+            for stream in (proc.stdout, proc.stderr):
+                if stream is not None:
+                    with contextlib.suppress(OSError):
+                        stream.close()
+            for thread in self._threads:
+                thread.join(timeout=deadline)
+            self._threads = []
+
+    def _stop(self, *, force: bool) -> None:
+        proc = self._proc
+        assert proc is not None
+        try:
+            if os.name == "posix":
+                os.killpg(proc.pid, signal.SIGKILL if force else signal.SIGTERM)
+            elif force:
+                proc.kill()
+            else:
+                proc.terminate()
+        except (ProcessLookupError, PermissionError):
+            pass
+
+    # ---- MCP operations ----------------------------------------------------------------
+
+    def list_tools(self) -> list[dict[str, Any]]:
+        """Return every tool descriptor (``name``, ``description``, ``inputSchema``)."""
+        tools: list[dict[str, Any]] = []
+        cursor: str | None = None
+        for _ in range(MAX_LIST_PAGES):
+            params = {} if cursor is None else {"cursor": cursor}
+            result = self._request("tools/list", params, self._request_timeout)
+            page = result.get("tools")
+            if not isinstance(page, list) or not all(isinstance(t, dict) for t in page):
+                raise self._fail(ProtocolError("tools/list result has no tools array."))
+            tools.extend(page)
+            cursor = result.get("nextCursor")
+            if cursor is None:
+                return tools
+            if not isinstance(cursor, str) or not cursor:
+                raise self._fail(ProtocolError("tools/list returned an invalid nextCursor."))
+        raise self._fail(ProtocolError(f"tools/list did not finish within {MAX_LIST_PAGES} pages."))
+
+    def call_tool(self, name: str, arguments: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        """Call one tool and return its structured result.
+
+        Raises :class:`ToolError` when the server sets ``isError`` and :class:`RpcError` when
+        it answers with a JSON-RPC error.
+        """
+        result = self._request(
+            "tools/call",
+            {"name": name, "arguments": dict(arguments or {})},
+            self._request_timeout,
+        )
+        content = result.get("content")
+        if not isinstance(content, list):
+            raise self._fail(ProtocolError(f"{name} result has no content array."))
+        is_error = result.get("isError", False)
+        if not isinstance(is_error, bool):
+            raise self._fail(ProtocolError(f"{name} result has a non-boolean isError."))
+        text = next(
+            (
+                item["text"]
+                for item in content
+                if isinstance(item, dict)
+                and item.get("type") == "text"
+                and isinstance(item.get("text"), str)
+            ),
+            "",
+        )
+        structured = result.get("structuredContent")
+        if structured is not None and not isinstance(structured, dict):
+            raise self._fail(ProtocolError(f"{name} structuredContent is not an object."))
+        if structured is None and text:
+            try:
+                parsed = json.loads(text)
+            except ValueError:
+                parsed = None
+            structured = parsed if isinstance(parsed, dict) else None
+        if is_error:
+            raise ToolError(name, structured or {}, text)
+        if structured is None:
+            raise self._fail(ProtocolError(f"{name} returned no structured result."))
+        return structured
+
+    def read(self, source: str) -> dict[str, Any]:
+        """``read``: ``revision_sha256``, compact ``html`` and anchored ``blocks``."""
+        return self.call_tool("read", {"source": source})
+
+    def search(self, source: str, query: str) -> dict[str, Any]:
+        """``search``: the source revision and anchored ``matches`` for a literal query."""
+        return self.call_tool("search", {"source": source, "query": query})
+
+    def edit(
+        self,
+        source: str,
+        revision_sha256: str,
+        output_dir: str,
+        edits: Sequence[Mapping[str, str]],
+        *,
+        approved: bool,
+        tracking: Mapping[str, str] | None = None,
+        render: bool | None = None,
+    ) -> dict[str, Any]:
+        """``edit``: reconcile ``old_html``/``new_html`` pairs into a new DOCX in ``output_dir``."""
+        arguments: dict[str, Any] = {
+            "source": source,
+            "revision_sha256": revision_sha256,
+            "output_dir": output_dir,
+            "approved": approved,
+            "edits": [dict(pair) for pair in edits],
+        }
+        if tracking is not None:
+            arguments["tracking"] = dict(tracking)
+        if render is not None:
+            arguments["render"] = render
+        return self.call_tool("edit", arguments)
+
+    def wolf_observe(self, request: Mapping[str, Any]) -> dict[str, Any]:
+        """``wolf_observe`` with a native agent request (the tool takes the request itself)."""
+        return self.call_tool("wolf_observe", request)
+
+    def wolf_transact(self, request: Mapping[str, Any]) -> dict[str, Any]:
+        """``wolf_transact`` with a native agent request."""
+        return self.call_tool("wolf_transact", request)
+
+    def wolf_diff(self, request: Mapping[str, Any]) -> dict[str, Any]:
+        """``wolf_diff`` with a native agent request."""
+        return self.call_tool("wolf_diff", request)
+
+    def lifecycle(
+        self, phase: str, transaction: str, *, approved: bool | None = None
+    ) -> dict[str, Any]:
+        """Continue a retained transaction: ``plan``, ``apply``, ``verify``, ``attest``,
+        ``commit`` (needs ``approved=True``) or ``discard``, as ``lifecycle_<phase>``."""
+        arguments: dict[str, Any] = {"transaction": transaction}
+        if approved is not None:
+            arguments["approved"] = approved
+        return self.call_tool(f"lifecycle_{phase}", arguments)
+
+    # ---- transport ---------------------------------------------------------------------
+
+    def _pump_stdout(self, stream: Any) -> None:
+        try:
+            while True:
+                line = stream.readline(MAX_MESSAGE_BYTES + 1)
+                if not line:
+                    break
+                self._lines.put(line)
+        except (OSError, ValueError):
+            pass
+        finally:
+            self._lines.put(_EOF)
+
+    def _pump_stderr(self, stream: Any) -> None:
+        try:
+            while chunk := stream.read1(4096):
+                with self._stderr_lock:
+                    self._stderr.append(chunk)
+                    self._stderr_size += len(chunk)
+                    while self._stderr_size > STDERR_TAIL_BYTES and len(self._stderr) > 1:
+                        self._stderr_size -= len(self._stderr.popleft())
+        except (OSError, ValueError):
+            pass
+
+    def _stderr_tail(self) -> str:
+        with self._stderr_lock:
+            data = b"".join(self._stderr)[-STDERR_TAIL_BYTES:]
+        return data.decode("utf-8", errors="replace").strip()
+
+    def _fail(self, error: WolfAgentError) -> WolfAgentError:
+        """Record a fatal session error and stop the child; the stream cannot be trusted."""
+        if self._failure is None:
+            self._failure = error
+        self.close()
+        return error
+
+    def _exited(self, message: str) -> WolfProcessError:
+        proc = self._proc
+        returncode = None
+        if proc is not None:
+            try:
+                returncode = proc.wait(timeout=2.0)
+            except subprocess.TimeoutExpired:
+                returncode = None
+        for thread in self._threads[1:]:  # let the stderr pump drain what the child wrote
+            thread.join(timeout=2.0)
+        return WolfProcessError(message, returncode=returncode, stderr=self._stderr_tail())
+
+    def _send(self, message: dict[str, Any]) -> None:
+        proc = self._proc
+        if proc is None or proc.stdin is None or proc.stdin.closed:
+            raise self._failure or WolfProcessError("The wolf mcp process is not running.")
+        data = (json.dumps(message, ensure_ascii=False, separators=(",", ":")) + "\n").encode()
+        try:
+            proc.stdin.write(data)
+            proc.stdin.flush()
+        except (OSError, ValueError) as error:
+            raise self._fail(self._exited("The wolf mcp process closed its input")) from error
+
+    def _request(self, method: str, params: dict[str, Any], timeout: float) -> dict[str, Any]:
+        with self._call_lock:
+            if self._failure is not None:
+                raise self._failure
+            if self._closed or self._proc is None:
+                raise WolfProcessError("The client is closed.")
+            self._next_id += 1
+            request_id = self._next_id
+            deadline = time.monotonic() + timeout
+            self._send({"jsonrpc": "2.0", "id": request_id, "method": method, "params": params})
+            while True:
+                try:
+                    line = self._lines.get(timeout=max(deadline - time.monotonic(), 0.0))
+                except queue.Empty:
+                    raise self._fail(
+                        WolfTimeoutError(f"No response to {method} within {timeout:g} seconds.")
+                    ) from None
+                if line is _EOF:
+                    raise self._fail(self._exited(f"The wolf mcp process ended during {method}"))
+                if len(line) > MAX_MESSAGE_BYTES:
+                    raise self._fail(ProtocolError("A response exceeded the message size limit."))
+                if not line.strip():
+                    continue
+                answer = self._classify(line, request_id, method)
+                if answer is not None:
+                    return answer
+
+    def _classify(self, line: bytes, request_id: int, method: str) -> dict[str, Any] | None:
+        """Return the result for ``request_id``, or ``None`` for a message to skip."""
+        try:
+            message = json.loads(line)
+        except ValueError:
+            raise self._fail(ProtocolError("The server wrote a line that is not JSON.")) from None
+        if not isinstance(message, dict) or message.get("jsonrpc") != "2.0":
+            raise self._fail(ProtocolError("The server wrote a message that is not JSON-RPC 2.0."))
+        if "method" in message:
+            if "id" in message:
+                self._answer_server_request(message)
+            return None
+        identifier = message.get("id")
+        if type(identifier) is not int or identifier != request_id:
+            raise self._fail(
+                ProtocolError(
+                    f"The response to {method} carries id {identifier!r}, not {request_id}."
+                )
+            )
+        if "error" in message:
+            error = message["error"]
+            if (
+                not isinstance(error, dict)
+                or type(error.get("code")) is not int
+                or not isinstance(error.get("message"), str)
+            ):
+                raise self._fail(ProtocolError(f"The error response to {method} is malformed."))
+            raise RpcError(error["code"], error["message"], error.get("data"))
+        result = message.get("result")
+        if not isinstance(result, dict):
+            raise self._fail(ProtocolError(f"The response to {method} has no result object."))
+        return result
+
+    def _answer_server_request(self, message: dict[str, Any]) -> None:
+        if message.get("method") == "ping":
+            self._send({"jsonrpc": "2.0", "id": message["id"], "result": {}})
+        else:
+            self._send(
+                {
+                    "jsonrpc": "2.0",
+                    "id": message["id"],
+                    "error": {"code": -32601, "message": "Method not found"},
+                }
+            )

wolf_agent-0.1.0/src/wolf_agent/errors.py

@@ -0,0 +1,57 @@
+"""Exceptions raised by the wolf agent client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class WolfAgentError(Exception):
+    """Base class for every error this package raises about the MCP session."""
+
+
+class WolfProcessError(WolfAgentError):
+    """The ``wolf mcp`` process could not start, exited, or closed its pipes."""
+
+    def __init__(self, message: str, *, returncode: int | None = None, stderr: str = "") -> None:
+        detail = f"{message} (exit status {returncode})" if returncode is not None else message
+        if stderr:
+            detail = f"{detail}: {stderr}"
+        super().__init__(detail)
+        self.returncode = returncode
+        self.stderr = stderr
+
+
+class WolfTimeoutError(WolfAgentError, TimeoutError):
+    """The server did not answer inside the bounded wait; the process was stopped."""
+
+
+class ProtocolError(WolfAgentError):
+    """The server broke the newline-delimited JSON-RPC contract."""
+
+
+class RpcError(WolfAgentError):
+    """The server answered a request with a JSON-RPC error object."""
+
+    def __init__(self, code: int, message: str, data: Any = None) -> None:
+        super().__init__(f"JSON-RPC error {code}: {message}")
+        self.code = code
+        self.message = message
+        self.data = data
+
+
+class ToolError(WolfAgentError):
+    """A tool call completed with ``isError`` set: a typed refusal or a failed engine.
+
+    ``document`` is the structured result (for example an ``edit`` refusal with ``code``,
+    ``message`` and ``hint``), or ``{}`` when the server returned only text.
+    """
+
+    def __init__(self, tool: str, document: dict[str, Any], text: str) -> None:
+        self.tool = tool
+        self.document = document
+        self.text = text
+        self.code = document.get("code") if isinstance(document.get("code"), str) else None
+        self.hint = document.get("hint") if isinstance(document.get("hint"), str) else None
+        message = document.get("message")
+        summary = message if isinstance(message, str) else text
+        super().__init__(f"{tool} refused{f' ({self.code})' if self.code else ''}: {summary}")

wolf_agent-0.1.0/tests/fake_wolf.py

@@ -0,0 +1,126 @@
+"""A scripted stand-in for ``wolf mcp`` used only by the SDK protocol tests.
+
+Run as ``python fake_wolf.py mcp --workspace-root ROOT``. ``FAKE_WOLF_MODE`` selects the
+behaviour; ``FAKE_WOLF_PIDFILE`` receives the server's process id so a test can prove the
+process is gone after the client closes.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import sys
+import time
+
+MODE = os.environ.get("FAKE_WOLF_MODE", "ok")
+
+
+def send(message: dict) -> None:
+    sys.stdout.write(json.dumps(message) + "\n")
+    sys.stdout.flush()
+
+
+def reply(message: dict, result: dict) -> None:
+    send({"jsonrpc": "2.0", "id": message["id"], "result": result})
+
+
+def tool_result(document: dict, *, error: bool = False) -> dict:
+    return {
+        "content": [{"type": "text", "text": json.dumps(document)}],
+        "structuredContent": document,
+        "isError": error,
+    }
+
+
+def main() -> int:
+    if pidfile := os.environ.get("FAKE_WOLF_PIDFILE"):
+        with open(pidfile, "w", encoding="utf-8") as handle:
+            handle.write(str(os.getpid()))
+    if MODE == "exit_before_init":
+        sys.stderr.write("boom: cannot open workspace\n")
+        return 3
+    if MODE == "stubborn":
+        signal.signal(signal.SIGTERM, signal.SIG_IGN)
+    for raw in sys.stdin:
+        message = json.loads(raw)
+        method = message.get("method")
+        if method == "initialize":
+            reply(
+                message,
+                {
+                    "protocolVersion": message["params"]["protocolVersion"],
+                    "capabilities": {"tools": {}},
+                    "serverInfo": {"name": "fake-wolf", "version": "0"},
+                    "instructions": "fake",
+                },
+            )
+        elif method == "notifications/initialized":
+            continue
+        elif method == "tools/list":
+            if MODE == "garbage":
+                sys.stdout.write("this is not json\n")
+                sys.stdout.flush()
+                continue
+            if MODE == "wrong_id":
+                send({"jsonrpc": "2.0", "id": message["id"] + 100, "result": {"tools": []}})
+                continue
+            cursor = message["params"].get("cursor")
+            if cursor is None:
+                reply(message, {"tools": [{"name": "read"}, {"name": "search"}], "nextCursor": "2"})
+            else:
+                reply(message, {"tools": [{"name": "edit"}]})
+        elif method == "tools/call":
+            if MODE in ("hang", "stubborn"):
+                time.sleep(3600)
+            handle_call(message)
+        else:
+            send(
+                {
+                    "jsonrpc": "2.0",
+                    "id": message["id"],
+                    "error": {"code": -32601, "message": "Method not found"},
+                }
+            )
+    if MODE == "stubborn":
+        time.sleep(3600)
+    return 0
+
+
+def handle_call(message: dict) -> None:
+    name = message["params"]["name"]
+    arguments = message["params"]["arguments"]
+    # A notification and a server-initiated ping must not disturb the pending call.
+    send({"jsonrpc": "2.0", "method": "notifications/message", "params": {"level": "info"}})
+    send({"jsonrpc": "2.0", "id": "srv-1", "method": "ping"})
+    pong = json.loads(sys.stdin.readline())
+    if pong != {"jsonrpc": "2.0", "id": "srv-1", "result": {}}:
+        sys.exit(9)
+    if name == "refuse":
+        document = {
+            "status": "refused",
+            "code": "stale-revision",
+            "message": "The source changed after read.",
+            "hint": "Read the current source.",
+        }
+        reply(message, tool_result(document, error=True))
+    elif name == "rpc_error":
+        send(
+            {
+                "jsonrpc": "2.0",
+                "id": message["id"],
+                "error": {"code": -32602, "message": "Invalid params", "data": {"at": "x"}},
+            }
+        )
+    elif name == "text_only":
+        reply(message, {"content": [{"type": "text", "text": '{"n": 1}'}], "isError": False})
+    elif name == "prose":
+        reply(message, {"content": [{"type": "text", "text": "plain prose"}], "isError": False})
+    elif name == "text_error":
+        reply(message, {"content": [{"type": "text", "text": "no-such: gone"}], "isError": True})
+    else:
+        reply(message, tool_result({"tool": name, "arguments": arguments}))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

wolf_agent-0.1.0/tests/test_client.py

@@ -0,0 +1,140 @@
+"""Consumer-visible protocol errors and process lifetime of the wolf agent client."""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from pathlib import Path
+
+import pytest
+from wolf_agent import (
+    ProtocolError,
+    RpcError,
+    ToolError,
+    WolfAgentClient,
+    WolfProcessError,
+    WolfTimeoutError,
+)
+
+FAKE = Path(__file__).with_name("fake_wolf.py")
+
+
+def client(tmp_path: Path, mode: str = "ok", **options) -> WolfAgentClient:
+    env = {**os.environ, "FAKE_WOLF_MODE": mode, "FAKE_WOLF_PIDFILE": str(tmp_path / "pid")}
+    return WolfAgentClient(tmp_path, wolf=[sys.executable, str(FAKE)], env=env, **options)
+
+
+def pid_of(tmp_path: Path) -> int:
+    return int((tmp_path / "pid").read_text())
+
+
+def alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    return True
+
+
+def test_is_error_result_raises_a_typed_refusal_and_keeps_the_session(tmp_path: Path) -> None:
+    with client(tmp_path) as wolf:
+        with pytest.raises(ToolError) as refused:
+            wolf.call_tool("refuse")
+        assert refused.value.tool == "refuse"
+        assert refused.value.code == "stale-revision"
+        assert refused.value.hint == "Read the current source."
+        assert refused.value.document["status"] == "refused"
+        assert wolf.call_tool("later") == {"tool": "later", "arguments": {}}
+        with pytest.raises(ToolError) as bare:
+            wolf.call_tool("text_error")
+        assert bare.value.code is None
+        assert bare.value.document == {}
+        assert "no-such: gone" in str(bare.value)
+
+
+def test_json_rpc_error_raises_rpc_error_without_ending_the_session(tmp_path: Path) -> None:
+    with client(tmp_path) as wolf:
+        with pytest.raises(RpcError) as error:
+            wolf.call_tool("rpc_error")
+        assert (error.value.code, error.value.message) == (-32602, "Invalid params")
+        assert error.value.data == {"at": "x"}
+        assert wolf.call_tool("after")["tool"] == "after"
+
+
+def test_text_json_is_used_when_structured_content_is_absent(tmp_path: Path) -> None:
+    with client(tmp_path) as wolf:
+        assert wolf.call_tool("text_only") == {"n": 1}
+        with pytest.raises(ProtocolError):
+            wolf.call_tool("prose")
+        assert wolf.returncode is not None
+
+
+def test_garbage_output_is_a_protocol_error_and_stops_the_process(tmp_path: Path) -> None:
+    wolf = client(tmp_path, "garbage")
+    wolf.start()
+    with pytest.raises(ProtocolError, match="not JSON"):
+        wolf.list_tools()
+    assert wolf.returncode is not None
+    assert not alive(pid_of(tmp_path))
+    with pytest.raises(ProtocolError):
+        wolf.list_tools()
+
+
+def test_response_with_the_wrong_id_is_a_protocol_error(tmp_path: Path) -> None:
+    wolf = client(tmp_path, "wrong_id")
+    wolf.start()
+    with pytest.raises(ProtocolError, match="carries id"):
+        wolf.list_tools()
+    assert not alive(pid_of(tmp_path))
+
+
+def test_process_exit_before_initialize_reports_status_and_stderr(tmp_path: Path) -> None:
+    with pytest.raises(WolfProcessError) as failed:
+        client(tmp_path, "exit_before_init").start()
+    assert failed.value.returncode == 3
+    assert "boom: cannot open workspace" in failed.value.stderr
+
+
+def test_missing_executable_is_a_process_error(tmp_path: Path) -> None:
+    with pytest.raises(WolfProcessError, match="Cannot start"):
+        WolfAgentClient(tmp_path, wolf=str(tmp_path / "no-such-wolf")).start()
+
+
+def test_unanswered_request_times_out_and_the_process_is_stopped(tmp_path: Path) -> None:
+    wolf = client(tmp_path, "hang", request_timeout=0.4, shutdown_timeout=1.0)
+    wolf.start()
+    began = time.monotonic()
+    with pytest.raises(WolfTimeoutError):
+        wolf.call_tool("read", {"source": "a.docx"})
+    assert time.monotonic() - began < 10
+    assert wolf.returncode is not None
+    assert not alive(pid_of(tmp_path))
+    with pytest.raises(WolfTimeoutError):
+        wolf.call_tool("read", {"source": "a.docx"})
+
+
+def test_close_escalates_to_kill_when_the_server_ignores_eof_and_sigterm(tmp_path: Path) -> None:
+    wolf = client(tmp_path, "stubborn", shutdown_timeout=0.3)
+    wolf.start()
+    began = time.monotonic()
+    wolf.close()
+    assert time.monotonic() - began < 10
+    assert not alive(pid_of(tmp_path))
+    wolf.close()
+
+
+def test_context_exit_lets_a_well_behaved_server_exit_cleanly(tmp_path: Path) -> None:
+    with client(tmp_path) as wolf:
+        wolf.list_tools()
+    assert wolf.returncode == 0
+    assert not alive(pid_of(tmp_path))
+    with pytest.raises(WolfProcessError, match="closed"):
+        wolf.list_tools()
+
+
+def test_workspace_root_must_be_an_existing_directory(tmp_path: Path) -> None:
+    with pytest.raises(ValueError, match="not a directory"):
+        WolfAgentClient(tmp_path / "missing")
+    with pytest.raises(ValueError, match="positive"):
+        WolfAgentClient(tmp_path, request_timeout=0)