slopper 0.1.0__py3-none-any.whl

slopper-0.1.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: slopper
+Version: 0.1.0
+Summary: Run Claude Code and Codex agent sessions for Folio on your own machine.
+Keywords: agents,claude-code,codex,folio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pycrdt>=0.12.0
+Requires-Dist: claude-agent-sdk<0.3,>=0.2.152
+Requires-Dist: openai-codex-cli-bin<0.157,>=0.156
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: websockets>=13.0
+Requires-Dist: pydantic-settings>=2.2.0
+Requires-Dist: python-json-logger>=2.0.0
+
+# slopper
+
+Run Folio agent sessions — Claude Code or Codex — on your own machine.
+
+`slopper` is the environment a Folio session runs in. It registers with your
+Folio server, picks up the sessions assigned to it, checks out the project's
+repositories into a workspace per session, and runs the agent there. Every
+tool call that needs your approval shows up in the session in Folio; the
+agent waits until you answer.
+
+Runs on **macOS** and **Linux**, Python 3.11+. Both agent CLIs are installed
+with the package.
+
+## Install
+
+```bash
+uv tool install slopper        # or: pipx install slopper
+```
+
+## Set up
+
+1. **Sign the agents in**, once per machine, as the user the service will run as:
+
+   ```bash
+   claude login                  # Claude Code
+   codex login                   # Codex (optional)
+   ```
+
+2. **Point it at Folio** with an API key from Folio's settings:
+
+   ```bash
+   slopper configure --server https://api.folio.example.com --token <api-key>
+   ```
+
+   This writes `~/.slopper/config.toml`, readable only by you.
+
+3. **Check everything**:
+
+   ```bash
+   slopper doctor
+   ```
+
+4. **Run it as a service** — started now, at every login, and again if it crashes:
+
+   ```bash
+   slopper service install
+   ```
+
+   - **macOS:** a LaunchAgent (`~/Library/LaunchAgents/slopper.plist`) in your
+     login session, so it can use the Claude login in your Keychain.
+     Logs: `~/Library/Logs/slopper/slopper.log`.
+   - **Linux:** a systemd user unit (`~/.config/systemd/user/slopper.service`).
+     Logs: `journalctl --user -u slopper`. To keep it running while you are
+     logged out (a headless machine): `sudo loginctl enable-linger $USER`.
+
+## Commands
+
+| Command | |
+|---|---|
+| `slopper configure` | Write `~/.slopper/config.toml` (`--server`, `--token`, `--env-id`, `--workspace`) |
+| `slopper doctor` | Check the config, the server, the key, git, and both agents' logins |
+| `slopper service install` · `uninstall` | Install or remove the service |
+| `slopper service start` · `stop` · `restart` · `status` | Control it |
+| `slopper service logs [-f]` | Show (or follow) its log |
+| `slopper run` | Run in the foreground instead of as a service |
+
+Only one environment runs per user account; a second `slopper run` refuses to
+start while the service is running.
+
+## Upgrade
+
+```bash
+uv tool upgrade slopper && slopper service restart
+```
+
+The service runs the installed interpreter by path, so it picks up the new
+version on restart — there is nothing to reinstall.
+
+## Configuration
+
+`~/.slopper/config.toml` holds the settings; environment variables of the
+same name override it.
+
+| Setting | Default | |
+|---|---|---|
+| `SLOPPER_SERVER_URL` | `http://localhost:8000` | Folio API |
+| `SLOPPER_TOKEN` | — | API key this environment registers with |
+| `SLOPPER_ENV_ID` | generated once, kept in `~/.slopper/identity.toml` | This machine's name in Folio. Must stay stable: sessions are bound to it |
+| `SLOPPER_WORKSPACE_ROOT` | `~/.slopper/workspaces` | One directory per session |
+| `SLOPPER_CLONE_SINCE` | `1.month.ago` | How much git history a checkout carries; empty for all |
+| `SLOPPER_CODEX_BIN` | the bundled one | A different `codex` binary |

slopper-0.1.0.dist-info/RECORD

@@ -0,0 +1,34 @@
+slopper_env/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+slopper_env/__main__.py,sha256=sQ6a1m5lUARAT4diQ1vWB8Q45Yf1MBkdiTss4gMy6-0,132
+slopper_env/agent.py,sha256=PKnsx8bynTskyUyrMKYKxXBHTfVcvSDxJSofhlFE_Js,6642
+slopper_env/cli.py,sha256=mZ4uL9MBrwLFNbhvdnvoQeiJOjUNd2lDaIknf6bfmYo,11392
+slopper_env/config.py,sha256=-kmfqpsYNo3AN3ZL9m0kQlCn1Ak5ovaBwsbfbqQzs5c,4064
+slopper_env/constants.py,sha256=h009BxGnp2A-SyImMWfyyB0AIiQ6tgnU6zQud9oRqTE,660
+slopper_env/devtools.py,sha256=mTPMZlPtUWsqMPBpC8r9OY5WU2b4cuYIHxrtkol5_xY,7021
+slopper_env/doc.py,sha256=m7Y0lbJjMY7YAJ5llwmiw9LhnJ7P1EIDEDq4qDtP7-M,59804
+slopper_env/folio_mcp.py,sha256=3LCgnLO_3_pYHVgvwT_GsUww6VG1_eAMRI1IofAyOFE,2813
+slopper_env/identity.py,sha256=8cPZ77kCX1QufJpLkN5jWqZb26dswibGoFeD5-aIW-0,2707
+slopper_env/ids.py,sha256=PiDUwk7MZEo1ULNn7UJwWf8H8UNnAMsFG3l9SsrOCD8,858
+slopper_env/lock.py,sha256=gylCYceT1Dvo2q6lFmTpUBYWqvKIVp-Y3A_TpiDJgoM,1882
+slopper_env/loop.py,sha256=w2MXysbGJ4KlAgA_7KDtHr1R36bZgEZdo-cqTWt_r2k,8865
+slopper_env/main.py,sha256=39s7o3jKeg7LEUf5yFr-4-vi7-lGq93xwCRhcoKx_1c,13420
+slopper_env/models.py,sha256=KadlFWHBujTtNZD26f0cjvns-Gmob0sZn9pfblt4sTs,4951
+slopper_env/ordering.py,sha256=A7pWh1DkXDrLC9OZaS_dl3wXBeXijApTWMo8d84VmzA,4884
+slopper_env/registration.py,sha256=yaD-KjyfGSLeoFso2RVb7HKg51GiPIgPsiNMwFTRIYs,4833
+slopper_env/runner.py,sha256=aiaAAptSO4rwtkvcvfdKhyZaQyzAmf2GsBnpvnoFW-M,8411
+slopper_env/service.py,sha256=c6f7ebkAxzd_WhZQLeI2ySQ3CBYZqez-c2cR6RVcLQk,8940
+slopper_env/sync.py,sha256=bZD1lLekKRM8Mr2_T8KmY4zbIq15zZTP6I4ZYbAukj4,8364
+slopper_env/workspace.py,sha256=996xqKQ7uoCgFr5IaYCilQ8kRoO4Fu_IaSjWs_AX4XA,13331
+slopper_env/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+slopper_env/adapters/base.py,sha256=xhhvq4qADuA-N2SDPkh1LQ5ljBY3r0QCBT4I5xwYdO4,1386
+slopper_env/adapters/claude_code.py,sha256=nB7Ylb6zg8V5hPfYscGD1-56lRNDyA24XcJaPvIyP08,6807
+slopper_env/adapters/codex.py,sha256=_D5gJZJ9n-6VVRLu4tLJoA65JL7R1VFKNI8B88NxXkY,8425
+slopper_env/backends/__init__.py,sha256=mpcZ7wXN910ZCq3hvzf6LiynPEd-D6Mu1v8ncMsJBv4,719
+slopper_env/backends/base.py,sha256=Uz3c-awxLYpb8NuLnPPUUS3oaE9PSOBEwLT-TB2-xv8,2690
+slopper_env/backends/claude.py,sha256=9oC3FDY8efFSOZFJwAbwzfS4ebjrgPPvLDybWFR_Awk,8341
+slopper_env/backends/codex.py,sha256=IE7NXo_7C3K3zU7mKtKocdqYQ9p67Sl5cx9KiVEIEOA,18153
+slopper-0.1.0.dist-info/METADATA,sha256=DUkVAP92RMxiPnUJD8X_QvFV0ldbvKCpLr-u8bkRFi4,4099
+slopper-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+slopper-0.1.0.dist-info/entry_points.txt,sha256=GmIIHP2kAcn_QmEGsMYzuyOKBMgYGutw4lg79zjbMvI,128
+slopper-0.1.0.dist-info/top_level.txt,sha256=WqIoIhel29y542bultciwMbCXyXonN5B8atEYBy-NgU,12
+slopper-0.1.0.dist-info/RECORD,,

slopper-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

slopper-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+slopper = slopper_env.cli:main
+slopper-dev = slopper_env.devtools:cli
+slopper-env = slopper_env.cli:run_alias

slopper-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+slopper_env

slopper_env/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m slopper_env`` -- what the installed service runs."""
+
+import sys
+
+from slopper_env.cli import main
+
+sys.exit(main())

slopper_env/adapters/base.py

@@ -0,0 +1,44 @@
+"""The provider seam.
+
+This interface is the only place in the environment where a provider is
+named. ``TurnRunner``, ``ConversationLoop``, the document, and the UI all
+operate on canonical items alone.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Sequence
+
+
+@dataclass(frozen=True)
+class TurnEnd:
+    """The provider's account of how a turn finished, in neutral terms."""
+
+    #: The provider's own session (Claude) or thread (Codex) id, recorded so
+    #: a later attach can resume it.
+    session_id: str | None
+    #: The turn ended on a tool call waiting for a human, to be resumed.
+    deferred: bool = False
+
+
+class AgentAdapter(ABC):
+    kind: str
+
+    @abstractmethod
+    def from_provider(self, message: Any) -> list[dict]:
+        """Translate one provider message into canonical items.
+
+        Returns a list because a single provider message may carry several
+        canonical items, and because some provider messages (usage reports,
+        lifecycle chatter) carry none.
+        """
+
+    @abstractmethod
+    def turn_end(self, message: Any) -> TurnEnd | None:
+        """The turn's outcome if ``message`` is the one that ends it."""
+
+    @abstractmethod
+    def to_provider(self, items: Sequence[dict]) -> Any:
+        """Translate canonical history into a provider payload."""

slopper_env/adapters/claude_code.py

@@ -0,0 +1,184 @@
+"""Claude Code adapter.
+
+Near-identity in the ingest direction: the canonical content model is
+Anthropic-shaped, and ``claude_agent_sdk`` emits exactly those blocks.
+
+The one restructuring happens on egress. Slopper stores tool output under
+``role="tool"``; the Messages API has no such role and requires it to travel
+inside a user message. That re-encoding lives here and nowhere else, so the
+stored transcript never claims a user said something they did not.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+import claude_agent_sdk as sdk
+
+from slopper_env.adapters.base import AgentAdapter, TurnEnd
+from slopper_env.ids import new_id
+from slopper_env.models import BlockType, ItemType, NON_CONTENT_ITEM_TYPES, Role
+
+
+class ClaudeCodeAdapter(AgentAdapter):
+    kind = "claude-code"
+
+    # ------------------------------------------------------------- ingest
+
+    def from_provider(self, message: Any) -> list[dict]:
+        if isinstance(message, sdk.AssistantMessage):
+            return self._assistant(message)
+        if isinstance(message, sdk.UserMessage):
+            return self._tool_results(message)
+        if isinstance(message, sdk.ResultMessage):
+            return []  # usage/cost is attached to the run, not a transcript item
+        return []
+
+    def turn_end(self, message: Any) -> TurnEnd | None:
+        """The session id rides on the terminal ResultMessage and nowhere else."""
+        if not isinstance(message, sdk.ResultMessage):
+            return None
+        return TurnEnd(
+            session_id=getattr(message, "session_id", None),
+            deferred=getattr(message, "stop_reason", None) == "tool_deferred",
+        )
+
+    def _assistant(self, message: sdk.AssistantMessage) -> list[dict]:
+        content = [self._block(block) for block in message.content]
+        content = [block for block in content if block is not None]
+        if not content:
+            return []
+        return [
+            {
+                "id": new_id(),
+                "type": ItemType.MESSAGE,
+                "role": Role.ASSISTANT,
+                "model": getattr(message, "model", None),
+                "content": content,
+            }
+        ]
+
+    def _tool_results(self, message: sdk.UserMessage) -> list[dict]:
+        """Tool output arrives from the SDK as a UserMessage.
+
+        That is the wire format's constraint, not a fact about who produced
+        it, so it is stored under ``role="tool"``.
+        """
+        if not isinstance(message.content, list):
+            return []
+        blocks = [
+            self._block(block)
+            for block in message.content
+            if isinstance(block, sdk.ToolResultBlock)
+        ]
+        blocks = [block for block in blocks if block is not None]
+        if not blocks:
+            return []
+        return [
+            {
+                "id": new_id(),
+                "type": ItemType.MESSAGE,
+                "role": Role.TOOL,
+                "content": blocks,
+            }
+        ]
+
+    def _block(self, block: Any) -> dict | None:
+        if isinstance(block, sdk.TextBlock):
+            return {"type": BlockType.TEXT, "text": block.text}
+
+        if isinstance(block, sdk.ThinkingBlock):
+            # `signature` must survive verbatim: Claude requires it back to
+            # accept a thinking block across tool-use turns. Never let a
+            # "normalize the block" helper drop it.
+            return {
+                "type": BlockType.THINKING,
+                "text": block.thinking,
+                "signature": block.signature,
+            }
+
+        if isinstance(block, sdk.ToolUseBlock):
+            return {
+                "type": BlockType.TOOL_USE,
+                "id": block.id,
+                "name": block.name,
+                "input": block.input,
+            }
+
+        if isinstance(block, sdk.ToolResultBlock):
+            return {
+                "type": BlockType.TOOL_RESULT,
+                "tool_use_id": block.tool_use_id,
+                "content": block.content,
+                "is_error": bool(block.is_error),
+            }
+
+        return None
+
+    # ------------------------------------------------------------- egress
+
+    def to_provider(self, items: Sequence[dict]) -> list[dict]:
+        """Rebuild Anthropic-format history from canonical items.
+
+        Not on the hot path -- ``ClaudeSDKClient`` owns session history, so a
+        normal turn sends new input only. This runs for cold resume.
+
+        Items that are transcript metadata rather than conversation content
+        are dropped here. Replaying an error banner would have the agent
+        responding to its own infrastructure failure as though the user had
+        reported it.
+        """
+        out: list[dict] = []
+        for item in items:
+            item_type = item.get("type")
+            if item_type in NON_CONTENT_ITEM_TYPES:
+                continue
+            if item_type == ItemType.RUN:
+                out.extend(self.to_provider(item.get("items") or []))
+                continue
+            if item_type != ItemType.MESSAGE:
+                continue
+            if item.get("is_meta") and item.get("role") == Role.SYSTEM:
+                continue
+
+            role = item.get("role")
+            content = [self._to_wire(b) for b in (item.get("content") or [])]
+            content = [b for b in content if b is not None]
+            if not content:
+                continue
+
+            # The Messages API has no tool role; tool output rides in a user
+            # message. Storage keeps them distinct, the wire does not.
+            wire_role = "user" if role == Role.TOOL else role
+            if wire_role not in ("user", "assistant"):
+                continue
+            out.append({"role": wire_role, "content": content})
+        return out
+
+    def _to_wire(self, block: dict) -> dict | None:
+        kind = block.get("type")
+        if kind == BlockType.TEXT:
+            return {"type": "text", "text": str(block.get("text", ""))}
+        if kind == BlockType.THINKING:
+            return {
+                "type": "thinking",
+                "thinking": block.get("text", ""),
+                "signature": block.get("signature", ""),
+            }
+        if kind == BlockType.TOOL_USE:
+            return {
+                "type": "tool_use",
+                "id": block.get("id"),
+                "name": block.get("name"),
+                "input": block.get("input") or {},
+            }
+        if kind == BlockType.TOOL_RESULT:
+            wire = {
+                "type": "tool_result",
+                "tool_use_id": block.get("tool_use_id"),
+                "content": block.get("content"),
+            }
+            if block.get("is_error"):
+                wire["is_error"] = True
+            return wire
+        return None

slopper_env/adapters/codex.py

@@ -0,0 +1,220 @@
+"""Codex adapter.
+
+Codex reports a turn as *items* -- an agent message, a reasoning summary, a
+command it ran, a file change, an MCP call -- each announced by
+``item/started`` and finished by ``item/completed`` over the app-server
+protocol. This turns them into the same canonical items the Claude adapter
+produces, so the document and the UI stay provider-blind:
+
+    agentMessage            -> assistant text
+    reasoning               -> assistant thinking (summary text, no signature)
+    commandExecution        -> tool_use "shell"       + tool_result
+    fileChange              -> tool_use "apply_patch" + tool_result
+    mcpToolCall             -> tool_use "mcp__<server>__<tool>" + tool_result
+    webSearch               -> tool_use "web_search"  + tool_result
+
+A tool call is written when it *starts*, so the transcript shows it running
+(and an approval card has a row to belong to); its result is written when it
+completes. Codex's item id is the tool_use id on both, which is also the id
+the approval request carries.
+
+Egress is not implemented: a Codex session's history lives in its own
+thread, resumed by id. Replaying canonical history into Codex is only needed
+for cross-provider forks, which do not exist yet.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+from slopper_env.adapters.base import AgentAdapter, TurnEnd
+from slopper_env.ids import new_id
+from slopper_env.models import BlockType, ItemType, Role
+
+#: Canonical tool names for Codex's built-in actions.
+SHELL = "shell"
+APPLY_PATCH = "apply_patch"
+WEB_SEARCH = "web_search"
+
+#: Item statuses that mean the action did not happen as asked.
+_FAILED = {"failed", "declined"}
+
+
+class CodexAdapter(AgentAdapter):
+    kind = "codex"
+
+    # ------------------------------------------------------------- ingest
+
+    def from_provider(self, message: Any) -> list[dict]:
+        method = message.get("method")
+        params = message.get("params") or {}
+        if method == "item/started":
+            call = tool_call(params.get("item") or {})
+            return [_assistant([call])] if call else []
+        if method == "item/completed":
+            return self._completed(params.get("item") or {})
+        if method == "turn/completed":
+            return self._failure(params.get("turn") or {})
+        return []
+
+    def turn_end(self, message: Any) -> TurnEnd | None:
+        if message.get("method") != "turn/completed":
+            return None
+        return TurnEnd(session_id=(message.get("params") or {}).get("threadId"))
+
+    def _completed(self, item: dict) -> list[dict]:
+        kind = item.get("type")
+        if kind == "agentMessage":
+            text = item.get("text") or ""
+            return [_assistant([{"type": BlockType.TEXT, "text": text}])] if text else []
+        if kind == "reasoning":
+            text = "\n\n".join(_strings(item.get("summary")))
+            if not text:
+                return []
+            # No signature: that is an Anthropic concept. The block is for the
+            # reader; Codex keeps its own reasoning in its thread.
+            return [_assistant([{"type": BlockType.THINKING, "text": text, "signature": ""}])]
+        result = tool_result(item)
+        if result is None:
+            return []
+        return [{"id": new_id(), "type": ItemType.MESSAGE, "role": Role.TOOL, "content": [result]}]
+
+    def _failure(self, turn: dict) -> list[dict]:
+        if turn.get("status") != "failed":
+            return []
+        error = turn.get("error") or {}
+        message = error.get("message") if isinstance(error, dict) else str(error)
+        return [
+            {
+                "type": ItemType.ERROR,
+                "source": "agent",
+                "code": "turn_failed",
+                "message": (message or "Codex reported the turn as failed.")[:2000],
+            }
+        ]
+
+    # ------------------------------------------------------------- egress
+
+    def to_provider(self, items: Sequence[dict]) -> Any:
+        raise NotImplementedError("Codex resumes its own thread; see module docstring")
+
+
+# ------------------------------------------------------------------ mapping
+
+
+def tool_call(item: dict) -> dict | None:
+    """The canonical tool_use block for a Codex item, or None if it is not one."""
+    kind = item.get("type")
+    item_id = item.get("id")
+    if not item_id:
+        return None
+    if kind == "commandExecution":
+        name, tool_input = SHELL, {"command": command_text(item)}
+    elif kind == "fileChange":
+        changes = [
+            {"path": c.get("path"), "kind": _kind(c.get("kind"))}
+            for c in item.get("changes") or []
+        ]
+        tool_input = {"changes": changes}
+        if changes:
+            # Named so the transcript labels the row by its file.
+            tool_input["path"] = changes[0]["path"]
+        name = APPLY_PATCH
+    elif kind == "mcpToolCall":
+        name = f"mcp__{item.get('server')}__{item.get('tool')}"
+        arguments = item.get("arguments")
+        tool_input = arguments if isinstance(arguments, dict) else {"arguments": arguments}
+    elif kind == "webSearch":
+        name, tool_input = WEB_SEARCH, {"query": item.get("query") or ""}
+    else:
+        return None
+    return {"type": BlockType.TOOL_USE, "id": item_id, "name": name, "input": tool_input}
+
+
+def tool_result(item: dict) -> dict | None:
+    """The canonical tool_result block for a finished Codex item."""
+    kind = item.get("type")
+    item_id = item.get("id")
+    if not item_id or kind not in ("commandExecution", "fileChange", "mcpToolCall", "webSearch"):
+        return None
+
+    failed = item.get("status") in _FAILED
+    if kind == "commandExecution":
+        exit_code = item.get("exitCode")
+        content = item.get("aggregatedOutput") or ""
+        if exit_code not in (None, 0):
+            failed = True
+            content = f"{content}\n(exit code {exit_code})".strip()
+        if item.get("status") == "declined":
+            content = content or "The user declined this."
+    elif kind == "fileChange":
+        content = "\n".join(
+            f"{_kind(c.get('kind'))} {c.get('path')}\n{c.get('diff') or ''}".rstrip()
+            for c in item.get("changes") or []
+        )
+        if item.get("status") == "declined":
+            content = "The user declined this."
+    elif kind == "mcpToolCall":
+        error = item.get("error")
+        if error:
+            failed = True
+            content = error.get("message") if isinstance(error, dict) else str(error)
+        else:
+            content = _mcp_text(item.get("result"))
+    else:
+        content = ""
+    return {
+        "type": BlockType.TOOL_RESULT,
+        "tool_use_id": item_id,
+        "content": content,
+        "is_error": failed,
+    }
+
+
+def command_text(item: dict) -> str:
+    """The command as the agent wrote it, not as Codex wrapped it.
+
+    Codex runs ``printf hi > f`` as ``/bin/zsh -lc 'printf hi > f'``; its
+    parsed ``commandActions`` keep the original, which is what a reader
+    recognises and what an approval card should show.
+    """
+    actions = item.get("commandActions") or []
+    if len(actions) == 1 and actions[0].get("command"):
+        return str(actions[0]["command"])
+    return str(item.get("command") or "")
+
+
+def _assistant(content: list[dict]) -> dict:
+    return {"id": new_id(), "type": ItemType.MESSAGE, "role": Role.ASSISTANT, "content": content}
+
+
+def _kind(kind: Any) -> str:
+    """A file change's kind: a plain string, or ``{"type": "update", ...}``."""
+    if isinstance(kind, dict):
+        return str(kind.get("type") or "update")
+    return str(kind or "update")
+
+
+def _strings(value: Any) -> list[str]:
+    if isinstance(value, str):
+        return [value] if value else []
+    if isinstance(value, list):
+        out = []
+        for part in value:
+            text = part.get("text") if isinstance(part, dict) else part
+            if isinstance(text, str) and text:
+                out.append(text)
+        return out
+    return []
+
+
+def _mcp_text(result: Any) -> str:
+    """MCP results carry content blocks; keep their text."""
+    if not isinstance(result, dict):
+        return "" if result is None else str(result)
+    texts = [
+        block.get("text", "")
+        for block in result.get("content") or []
+        if isinstance(block, dict) and block.get("type") == "text"
+    ]
+    return "\n".join(texts) if texts else str(result.get("structuredContent") or "")