mindwire 0.1.0__py3-none-any.whl

mindwire/__init__.py

@@ -0,0 +1,29 @@
+"""Synchronous and asynchronous clients for the MindWire runtime."""
+
+from ._client import AsyncMindwire, Mindwire
+from ._errors import (
+    APIError,
+    ConnectionError,
+    MindwireError,
+    RunFailedError,
+    TimeoutError,
+)
+from ._runs import AsyncRun, Run
+from ._types import Event, RunRecord, WaitResult
+from ._version import __version__
+
+__all__ = [
+    "APIError",
+    "AsyncMindwire",
+    "AsyncRun",
+    "ConnectionError",
+    "Event",
+    "Mindwire",
+    "MindwireError",
+    "Run",
+    "RunFailedError",
+    "RunRecord",
+    "TimeoutError",
+    "WaitResult",
+    "__version__",
+]

mindwire/_client.py

@@ -0,0 +1,277 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator, Mapping
+from typing import Any
+
+import httpx
+
+from ._errors import MindwireError
+from ._runs import AsyncRun, Run
+from ._transport import (
+    Connection,
+    async_events,
+    decode_response,
+    events,
+    network_errors,
+    run_record,
+    segment,
+    stream_timeout,
+)
+from ._types import Event
+
+Query = Mapping[str, str | int | float | bool | None]
+
+
+def turn_body(
+    chat_id: str,
+    message: str,
+    cwd: str | None,
+    options: Mapping[str, Any] | None,
+    request_id: str | None,
+    mode: str,
+    resolve: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {"chatId": chat_id, "message": message, "mode": mode}
+    for key, value in (
+        ("cwd", cwd),
+        ("options", options),
+        ("requestId", request_id),
+        ("resolve", resolve),
+    ):
+        if value is not None:
+            body[key] = value
+    return body
+
+
+class Mindwire:
+    """A synchronous connection to an existing local or remote MindWire runtime."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token: str | None = None,
+        agent: str | None = None,
+        timeout: float | None = 120.0,
+        headers: Mapping[str, str] | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._connection = Connection(base_url, token, agent, headers)
+        self._http = httpx.Client(
+            headers=self._connection.headers,
+            timeout=timeout,
+            transport=transport,
+            follow_redirects=False,
+        )
+
+    def __enter__(self) -> Mindwire:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close HTTP connections; admitted work continues on the runtime."""
+        self._http.close()
+
+    def request(
+        self, method: str, path: str, *, json: Any = None, params: Query | None = None
+    ) -> Any:
+        """Call any shared API endpoint using its native JSON fields."""
+        with network_errors():
+            response = self._http.request(
+                method, self._connection.url(path), json=json, params=params
+            )
+            return decode_response(response)
+
+    def stream(
+        self,
+        path: str,
+        *,
+        params: Query | None = None,
+        include_open_sentinel: bool = False,
+    ) -> Iterator[Event]:
+        with network_errors():
+            timeout = stream_timeout(self._http.timeout)
+            with self._http.stream(
+                "GET",
+                self._connection.url(path),
+                params=params,
+                headers={"Accept": "text/event-stream"},
+                timeout=timeout,
+            ) as response:
+                if not response.is_success:
+                    response.read()
+                    decode_response(response)
+                if "text/event-stream" not in response.headers.get("content-type", ""):
+                    raise MindwireError(
+                        "The runtime did not return an SSE event stream"
+                    )
+                response.encoding = "utf-8"
+                yield from events(response.iter_lines(), include_open_sentinel)
+
+    def health(self) -> dict[str, Any]:
+        value: dict[str, Any] = self.request("GET", "/healthz")
+        return value
+
+    def catalog(self) -> dict[str, Any]:
+        value: dict[str, Any] = self.request("GET", "/catalog")
+        return value
+
+    def turn(
+        self,
+        *,
+        chat_id: str,
+        message: str,
+        agent: str | None = None,
+        cwd: str | None = None,
+        options: Mapping[str, Any] | None = None,
+        request_id: str | None = None,
+        mode: str = "turn",
+        resolve: Mapping[str, Any] | None = None,
+    ) -> Run:
+        """Start work. Reuse request_id when retrying an unacknowledged request."""
+        data = self.request(
+            "POST",
+            "/turns",
+            params=self._connection.agent_params(agent),
+            json=turn_body(chat_id, message, cwd, options, request_id, mode, resolve),
+        )
+        return Run(self, run_record(data))
+
+    def run(self, run_id: str) -> Run:
+        return Run(self, run_record(self.request("GET", "/runs/" + segment(run_id))))
+
+    def latest_run(self, chat_id: str) -> Run | None:
+        data = self.request("GET", f"/chats/{segment(chat_id)}/run")
+        return Run(self, run_record(data)) if data is not None else None
+
+    def preview_handoff(self, chat_id: str) -> dict[str, Any]:
+        value: dict[str, Any] = self.request(
+            "GET", f"/chats/{segment(chat_id)}/handoff"
+        )
+        return value
+
+    def handoff(self, chat_id: str, input: Mapping[str, Any]) -> dict[str, Any]:
+        """Submit a handoff payload with stable request and destination IDs."""
+        value: dict[str, Any] = self.request(
+            "POST", f"/chats/{segment(chat_id)}/handoff", json=dict(input)
+        )
+        return value
+
+
+class AsyncMindwire:
+    """An asynchronous connection for Python applications and background services."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token: str | None = None,
+        agent: str | None = None,
+        timeout: float | None = 120.0,
+        headers: Mapping[str, str] | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._connection = Connection(base_url, token, agent, headers)
+        self._http = httpx.AsyncClient(
+            headers=self._connection.headers,
+            timeout=timeout,
+            transport=transport,
+            follow_redirects=False,
+        )
+
+    async def __aenter__(self) -> AsyncMindwire:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def request(
+        self, method: str, path: str, *, json: Any = None, params: Query | None = None
+    ) -> Any:
+        with network_errors():
+            response = await self._http.request(
+                method, self._connection.url(path), json=json, params=params
+            )
+            return decode_response(response)
+
+    async def stream(
+        self,
+        path: str,
+        *,
+        params: Query | None = None,
+        include_open_sentinel: bool = False,
+    ) -> AsyncIterator[Event]:
+        with network_errors():
+            timeout = stream_timeout(self._http.timeout)
+            async with self._http.stream(
+                "GET",
+                self._connection.url(path),
+                params=params,
+                headers={"Accept": "text/event-stream"},
+                timeout=timeout,
+            ) as response:
+                if not response.is_success:
+                    await response.aread()
+                    decode_response(response)
+                if "text/event-stream" not in response.headers.get("content-type", ""):
+                    raise MindwireError(
+                        "The runtime did not return an SSE event stream"
+                    )
+                response.encoding = "utf-8"
+                async for event in async_events(
+                    response.aiter_lines(), include_open_sentinel
+                ):
+                    yield event
+
+    async def health(self) -> dict[str, Any]:
+        value: dict[str, Any] = await self.request("GET", "/healthz")
+        return value
+
+    async def catalog(self) -> dict[str, Any]:
+        value: dict[str, Any] = await self.request("GET", "/catalog")
+        return value
+
+    async def turn(
+        self,
+        *,
+        chat_id: str,
+        message: str,
+        agent: str | None = None,
+        cwd: str | None = None,
+        options: Mapping[str, Any] | None = None,
+        request_id: str | None = None,
+        mode: str = "turn",
+        resolve: Mapping[str, Any] | None = None,
+    ) -> AsyncRun:
+        data = await self.request(
+            "POST",
+            "/turns",
+            params=self._connection.agent_params(agent),
+            json=turn_body(chat_id, message, cwd, options, request_id, mode, resolve),
+        )
+        return AsyncRun(self, run_record(data))
+
+    async def run(self, run_id: str) -> AsyncRun:
+        data = await self.request("GET", "/runs/" + segment(run_id))
+        return AsyncRun(self, run_record(data))
+
+    async def latest_run(self, chat_id: str) -> AsyncRun | None:
+        data = await self.request("GET", f"/chats/{segment(chat_id)}/run")
+        return AsyncRun(self, run_record(data)) if data is not None else None
+
+    async def preview_handoff(self, chat_id: str) -> dict[str, Any]:
+        value: dict[str, Any] = await self.request(
+            "GET", f"/chats/{segment(chat_id)}/handoff"
+        )
+        return value
+
+    async def handoff(self, chat_id: str, input: Mapping[str, Any]) -> dict[str, Any]:
+        value: dict[str, Any] = await self.request(
+            "POST", f"/chats/{segment(chat_id)}/handoff", json=dict(input)
+        )
+        return value

mindwire/_errors.py

@@ -0,0 +1,32 @@
+from typing import Any
+
+
+class MindwireError(Exception):
+    """Base error raised by the SDK."""
+
+
+class APIError(MindwireError):
+    """A non-success HTTP response, with the daemon's error body preserved."""
+
+    def __init__(self, status: int, method: str, path: str, body: Any) -> None:
+        self.status = status
+        self.method = method
+        self.path = path
+        self.body = body
+        detail = body.get("error", "") if isinstance(body, dict) else str(body)
+        super().__init__(f"{method} {path} returned {status}: {detail}")
+
+
+class ConnectionError(MindwireError):
+    """The runtime could not be reached or its connection was interrupted."""
+
+
+class TimeoutError(MindwireError):
+    """An HTTP operation timed out. A run may still be executing on the runtime."""
+
+
+class RunFailedError(MindwireError):
+    def __init__(self, run_id: str, status: str, detail: str = "") -> None:
+        self.run_id = run_id
+        self.status = status
+        super().__init__(f"run {run_id} {status}" + (f": {detail}" if detail else ""))

mindwire/_runs.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator, Mapping
+from typing import TYPE_CHECKING, Any
+
+from ._errors import RunFailedError
+from ._transport import run_record, segment
+from ._types import Event, RunRecord, WaitResult
+
+if TYPE_CHECKING:
+    from ._client import AsyncMindwire, Mindwire
+
+
+def completion(record: RunRecord, result: dict[str, Any] | None) -> WaitResult:
+    if record["status"] != "done":
+        detail = record.get("error", "")
+        if record["status"] not in ("error", "cancelled"):
+            detail = "event stream ended before the run reached a terminal state"
+        raise RunFailedError(record["id"], record["status"], detail)
+    return {"run": record, "result": result}
+
+
+class _RunBase:
+    def __init__(self, record: RunRecord) -> None:
+        self._record = run_record(record)
+        self._path = "/runs/" + segment(self._record["id"])
+
+    @property
+    def id(self) -> str:
+        return self._record["id"]
+
+    @property
+    def chat_id(self) -> str:
+        return self._record["chatId"]
+
+    @property
+    def status(self) -> str:
+        """The latest known status. Call refresh() to read it from the runtime."""
+        return self._record["status"]
+
+    @property
+    def value(self) -> RunRecord:
+        return self._record.copy()
+
+
+class Run(_RunBase):
+    def __init__(self, client: Mindwire, record: RunRecord) -> None:
+        super().__init__(record)
+        self._client = client
+
+    def stream(
+        self, *, after: int | None = None, include_open_sentinel: bool = False
+    ) -> Iterator[Event]:
+        """Replay and follow events; close the iterator when stopping early."""
+        return self._client.stream(
+            self._path + "/stream",
+            params={"after": after} if after is not None else None,
+            include_open_sentinel=include_open_sentinel,
+        )
+
+    def __iter__(self) -> Iterator[Event]:
+        return self.stream()
+
+    def refresh(self) -> RunRecord:
+        self._record = run_record(self._client.request("GET", self._path))
+        return self.value
+
+    def snapshot(self) -> dict[str, Any]:
+        value: dict[str, Any] = self._client.request("GET", self._path + "/snapshot")
+        self._record = run_record(value["run"])
+        return value
+
+    def cancel(self) -> None:
+        """Stop the work on the runtime, rather than just disconnecting its stream."""
+        self._client.request("POST", self._path + "/cancel")
+
+    def respond(self, input: Mapping[str, Any]) -> None:
+        """Answer an interaction with the shared API's response payload."""
+        self._client.request("POST", self._path + "/respond", json=dict(input))
+
+    def wait(self, *, throw_on_error: bool = True) -> WaitResult:
+        result = None
+        for event in self.stream():
+            if event["type"] == "result":
+                result = event.get("result")
+        record = self.refresh()
+        if throw_on_error:
+            return completion(record, result)
+        return {"run": record, "result": result}
+
+
+class AsyncRun(_RunBase):
+    def __init__(self, client: AsyncMindwire, record: RunRecord) -> None:
+        super().__init__(record)
+        self._client = client
+
+    def stream(
+        self, *, after: int | None = None, include_open_sentinel: bool = False
+    ) -> AsyncIterator[Event]:
+        """Replay and follow events. Use contextlib.aclosing when stopping early."""
+        return self._client.stream(
+            self._path + "/stream",
+            params={"after": after} if after is not None else None,
+            include_open_sentinel=include_open_sentinel,
+        )
+
+    def __aiter__(self) -> AsyncIterator[Event]:
+        return self.stream()
+
+    async def refresh(self) -> RunRecord:
+        self._record = run_record(await self._client.request("GET", self._path))
+        return self.value
+
+    async def snapshot(self) -> dict[str, Any]:
+        value: dict[str, Any] = await self._client.request(
+            "GET", self._path + "/snapshot"
+        )
+        self._record = run_record(value["run"])
+        return value
+
+    async def cancel(self) -> None:
+        await self._client.request("POST", self._path + "/cancel")
+
+    async def respond(self, input: Mapping[str, Any]) -> None:
+        await self._client.request("POST", self._path + "/respond", json=dict(input))
+
+    async def wait(self, *, throw_on_error: bool = True) -> WaitResult:
+        result = None
+        async for event in self.stream():
+            if event["type"] == "result":
+                result = event.get("result")
+        record = await self.refresh()
+        if throw_on_error:
+            return completion(record, result)
+        return {"run": record, "result": result}

mindwire/_transport.py

@@ -0,0 +1,166 @@
+import json
+from collections.abc import AsyncIterator, Iterator, Mapping
+from contextlib import contextmanager
+from typing import Any, cast
+from urllib.parse import quote, urlsplit
+
+import httpx
+
+from ._errors import APIError, ConnectionError, MindwireError, TimeoutError
+from ._types import Event, RunRecord
+from ._version import __version__
+
+
+def stream_timeout(timeout: httpx.Timeout) -> httpx.Timeout:
+    value = httpx.Timeout(timeout)
+    value.read = None
+    return value
+
+
+def segment(value: str) -> str:
+    if not value or value in (".", ".."):
+        raise ValueError("An identifier must be nonempty and cannot be '.' or '..'")
+    return quote(value, safe="")
+
+
+def run_record(value: Any) -> RunRecord:
+    if not isinstance(value, dict) or any(
+        not isinstance(value.get(key), str) for key in ("id", "chatId", "status")
+    ):
+        raise MindwireError("The runtime returned an invalid run record")
+    return cast(RunRecord, value)
+
+
+def decode_response(response: httpx.Response) -> Any:
+    if not response.is_success:
+        try:
+            body = response.json()
+        except ValueError:
+            body = response.text
+        raise APIError(
+            response.status_code,
+            response.request.method,
+            response.request.url.path,
+            body,
+        )
+    if response.status_code == 204 or not response.content:
+        return None
+    try:
+        return response.json()
+    except ValueError as error:
+        raise MindwireError("The runtime returned a non-JSON response") from error
+
+
+@contextmanager
+def network_errors() -> Iterator[None]:
+    try:
+        yield
+    except httpx.TimeoutException as error:
+        raise TimeoutError("The MindWire runtime request timed out") from error
+    except httpx.HTTPError as error:
+        raise ConnectionError("The MindWire runtime connection failed") from error
+
+
+class Connection:
+    def __init__(
+        self,
+        base_url: str,
+        token: str | None,
+        agent: str | None,
+        headers: Mapping[str, str] | None,
+    ) -> None:
+        parsed = urlsplit(base_url)
+        if (
+            parsed.scheme not in ("http", "https")
+            or not parsed.netloc
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.query
+            or parsed.fragment
+        ):
+            raise ValueError(
+                "base_url must be an HTTP(S) URL without credentials or query"
+            )
+        self.base_url = base_url.rstrip("/")
+        self.agent = agent
+        self.headers = httpx.Headers(headers or {})
+        self.headers.setdefault("Accept", "application/json")
+        self.headers.setdefault("User-Agent", f"mindwire-python/{__version__}")
+        if token:
+            self.headers["Authorization"] = f"Bearer {token}"
+
+    def url(self, path: str) -> str:
+        # Only relative API paths are accepted; tokens cannot be sent to another origin.
+        parsed = urlsplit(path)
+        if (
+            not path.startswith("/")
+            or path.startswith("//")
+            or "\\" in path
+            or parsed.scheme
+            or parsed.netloc
+            or parsed.query
+            or parsed.fragment
+        ):
+            raise ValueError(
+                "Use an API path beginning with '/', and pass params separately"
+            )
+        return self.base_url + path
+
+    def agent_params(self, agent: str | None = None) -> dict[str, str]:
+        selected = self.agent if agent is None else agent
+        return {"agent": selected} if selected else {}
+
+
+class SSEDecoder:
+    def __init__(self) -> None:
+        self.data: list[str] = []
+
+    def feed(self, line: str) -> Event | None:
+        if line == "":
+            return self.finish()
+        field, _, value = line.partition(":")
+        if field == "data":
+            self.data.append(value.removeprefix(" "))
+        return None
+
+    def finish(self) -> Event | None:
+        if not self.data:
+            return None
+        payload, self.data = "\n".join(self.data), []
+        try:
+            value = json.loads(payload)
+        except ValueError as error:
+            raise MindwireError("The runtime sent an invalid JSON event") from error
+        if not isinstance(value, dict) or not isinstance(value.get("type"), str):
+            raise MindwireError("The runtime sent an invalid event object")
+        return cast(Event, value)
+
+
+def is_open_sentinel(event: Event) -> bool:
+    return (
+        event["type"] == "status" and (event.get("meta") or {}).get("stream") == "open"
+    )
+
+
+def events(lines: Iterator[str], include_open_sentinel: bool) -> Iterator[Event]:
+    decoder = SSEDecoder()
+    for line in lines:
+        event = decoder.feed(line)
+        if event is not None and (include_open_sentinel or not is_open_sentinel(event)):
+            yield event
+    event = decoder.finish()
+    if event is not None and (include_open_sentinel or not is_open_sentinel(event)):
+        yield event
+
+
+async def async_events(
+    lines: AsyncIterator[str], include_open_sentinel: bool
+) -> AsyncIterator[Event]:
+    decoder = SSEDecoder()
+    async for line in lines:
+        event = decoder.feed(line)
+        if event is not None and (include_open_sentinel or not is_open_sentinel(event)):
+            yield event
+    event = decoder.finish()
+    if event is not None and (include_open_sentinel or not is_open_sentinel(event)):
+        yield event

mindwire/_types.py

@@ -0,0 +1,39 @@
+"""Wire payloads retain the shared API's field names, including camelCase keys."""
+
+from typing import Any, TypedDict
+
+
+class Event(TypedDict, total=False):
+    type: str
+    sequence: int
+    replay: bool
+    itemId: str
+    sessionId: str
+    text: str
+    delta: bool
+    result: dict[str, Any]
+    tool: dict[str, Any]
+    interaction: dict[str, Any]
+    error: str
+    meta: dict[str, Any]
+    at: str
+
+
+class _RunRequired(TypedDict):
+    id: str
+    chatId: str
+    status: str
+
+
+class RunRecord(_RunRequired, total=False):
+    agent: str
+    error: str
+    kind: str
+    parentId: str
+    stopReason: str
+    iterations: int
+
+
+class WaitResult(TypedDict):
+    run: RunRecord
+    result: dict[str, Any] | None

mindwire/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

mindwire-0.1.0.dist-info/METADATA

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: mindwire
+Version: 0.1.0
+Summary: Python SDK for building products with MindWire's shared coding-agent runtime.
+Project-URL: Homepage, https://mindwire.sh
+Project-URL: Documentation, https://github.com/oblien/mindwire/tree/main/packages/python
+Project-URL: Repository, https://github.com/oblien/mindwire
+Project-URL: Issues, https://github.com/oblien/mindwire/issues
+Author: Oblien
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,claude-code,codex,mindwire,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.28.1
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: mypy<2,>=1.18; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.14; extra == 'dev'
+Requires-Dist: twine<8,>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MindWire for Python
+
+Build products with the same agent runtime used by MindWire's TypeScript and Go
+SDKs. This initial Python SDK connects to an **existing local or remote runtime**
+over HTTP and server-sent events. It includes synchronous and asynchronous clients,
+turns, streaming, run snapshots, cancellation, interaction responses and conversation
+handoffs. The low-level `request()` method exposes the rest of the shared API.
+
+Requires Python 3.10 or newer. Licensed under Apache-2.0.
+
+## Install
+
+Once the first release is published:
+
+```sh
+pip install mindwire
+```
+
+For development from this repository:
+
+```sh
+python -m pip install -e './packages/python[dev]'
+```
+
+## Connect and run
+
+Start or connect to a [MindWire runtime](https://mindwire.sh/docs/guides/quickstart)
+and authenticate its agent. Set `MINDWIRE_BASE_URL` and `MINDWIRE_TOKEN` in your
+application environment. A local runtime usually listens on `http://127.0.0.1:8790`;
+use its configured bearer token. Use HTTPS for connections across the network.
+
+```python
+import os
+from mindwire import Mindwire
+
+with Mindwire(
+    base_url=os.environ["MINDWIRE_BASE_URL"],
+    token=os.environ["MINDWIRE_TOKEN"],
+    agent="codex",
+) as mw:
+    run = mw.turn(
+        chat_id="launch",
+        message="Read brief.md and write a launch plan.",
+        cwd="/workspace/product",  # A directory on the runtime's computer.
+    )
+    for event in run:
+        if event["type"] == "text":
+            print(event.get("text", ""), end="", flush=True)
+    outcome = run.wait()
+    print(outcome["run"]["status"])
+```
+
+`run.wait()` consumes the stream and checks the final run record. Calling it after
+iteration replays the stream internally to collect its result. It raises
+`RunFailedError` for errors, cancellation, or a stream ending before a terminal
+status. Pass `throw_on_error=False` to inspect that outcome yourself.
+
+The Python SDK does not install, launch or provision the runtime in this release.
+Local, Docker, SSH and cloud environments work when you provide a reachable
+runtime URL and token. Harness authentication and capability support are owned by
+the runtime; the SDK does not sign in to an agent on your behalf.
+
+## Async applications
+
+```python
+import asyncio
+import os
+from mindwire import AsyncMindwire
+
+async def main():
+    async with AsyncMindwire(
+        base_url=os.environ["MINDWIRE_BASE_URL"],
+        token=os.environ["MINDWIRE_TOKEN"],
+        agent="claude-code",
+    ) as mw:
+        run = await mw.turn(chat_id="research", message="Summarize this project.")
+        async for event in run:
+            if event["type"] == "text":
+                print(event.get("text", ""), end="", flush=True)
+        await run.wait()
+
+asyncio.run(main())
+```
+
+## Runs and streams
+
+- `mw.turn(...)` starts a turn. Supply `request_id` and retain it when retrying an
+  unacknowledged creation request on runtimes supporting `turnRequestVersion`.
+- `mw.run(run_id)` and `mw.latest_run(chat_id)` reattach to existing work.
+- `run.snapshot()` reads current output and its cursor;
+  `run.stream(after=snapshot["sequence"])` follows newer events on runtimes that
+  advertise cursor support.
+- `run.cancel()` stops execution. Closing a client or event stream only closes
+  observation; the runtime continues admitted work while it remains running.
+- `run.respond({...})` answers a supported interaction using the shared API payload.
+- `mw.turn(..., mode="resolve", resolve={"maxIterations": 5})` runs bounded
+  continuation when the selected harness supports it.
+
+To stop reading early, explicitly close the stream using `contextlib.closing`
+(sync) or `contextlib.aclosing` (async). For example:
+
+```python
+from contextlib import closing
+
+with closing(run.stream()) as stream:
+    for event in stream:
+        if event["type"] == "interaction":
+            break
+```
+
+Unary requests have a configurable timeout (`timeout=120.0`, in seconds). SSE
+streams have no read timeout so an agent can continue working through idle periods.
+The client does not automatically retry turns or reconnect interrupted streams.
+
+## Shared API and handoffs
+
+`mw.request(method, path, json=..., params=...)` returns the parsed response body.
+It accepts runtime API paths, not arbitrary URLs. All payloads, response objects,
+turn `options` and event fields retain the shared API's **camelCase** field names.
+Python method parameters use snake_case.
+
+```python
+bots = mw.request("GET", "/bots")
+config = mw.request("GET", "/config", params={"agent": "codex"})
+preview = mw.preview_handoff("launch")
+handoff = mw.handoff("launch", {
+    "newChatId": "launch-review",
+    "requestId": "launch-review-001",
+    "targetAgentId": "saved-claude-profile-id",
+    "task": "Review the plan and identify missing steps.",
+})
+review_run = mw.run(handoff["run"]["id"])
+```
+
+Handoffs require a compatible runtime, an eligible source conversation and a saved
+destination agent profile. Use `preview` to inspect the context before submission;
+see the [handoff guide](https://mindwire.sh/docs/guides/handoffs) for field semantics.
+
+`APIError` preserves `status`, `method`, `path` and the server's `body`.
+`ConnectionError` and `TimeoutError` identify transport failures. All inherit
+from `MindwireError`. Errors do not expose the configured bearer token.
+
+## Development and releases
+
+```sh
+cd packages/python
+python -m pytest
+ruff check src tests
+mypy src
+python -m build
+python -m twine check --strict dist/*
+```
+
+The Python package has its own version, initially `0.1.0`. The runtime and
+TypeScript package keep their existing release cycle. See [RELEASING.md](RELEASING.md)
+for PyPI setup and publishing.

mindwire-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+mindwire/__init__.py,sha256=LUqJ0b4sjwnLrAVmOK-zj-gDgKCIUUEYATirpdlAzfs,596
+mindwire/_client.py,sha256=6yPZ8-2vcHNM0REQhwp3sxoGZC_6uMdRuv_6BO6LNTs,9101
+mindwire/_errors.py,sha256=5753JSURYLox7fBdbBenKHT4d7Hq_3ssGw--pFiL4vg,1050
+mindwire/_runs.py,sha256=eKbOQuLna7123BnmGpMfMuXwImus4sxV-k5SuuSH01M,4738
+mindwire/_transport.py,sha256=PqOF6VW12B9coMd2F9dDE87QBGaFgR8ghQbbKhV83n4,5435
+mindwire/_types.py,sha256=jt6UENRrCYGoEp5c2Gb57uGlnUjxB7JHA2cyy-nUPX8,716
+mindwire/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+mindwire/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mindwire-0.1.0.dist-info/METADATA,sha256=uH6jK7sIC3NXnZO7bn0nwsGaH3tCdByn-L6OzwrjpPY,6956
+mindwire-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+mindwire-0.1.0.dist-info/licenses/LICENSE,sha256=APFxZEXfaKFVOR1npG2pCZ8xMijDhTFAM9_RKSBQvZ8,11350
+mindwire-0.1.0.dist-info/RECORD,,

mindwire-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mindwire-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 The mindwire authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.