langbot-plugin 0.4.2b4__tar.gz → 0.4.3__tar.gz

langbot_plugin-0.4.3/.github/workflows/cla.yml

@@ -0,0 +1,41 @@
+name: "CLA Assistant"
+on:
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [opened, closed, synchronize, reopened]
+
+permissions:
+  actions: write          # re-run the failed CLA check after signing
+  contents: read          # signatures are stored in the remote langbot-app/cla repo
+  pull-requests: write    # post guidance comments, lock PR after merge
+  statuses: write         # set the commit status
+
+jobs:
+  CLAAssistant:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "CLA Assistant"
+        if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
+        # Upstream repo was archived in 2026-03; pin to the v2.6.1 commit SHA.
+        uses: contributor-assistant/github-action@ca4a40a7d1004f18d9960b404b97e5f30a505a08 # v2.6.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # repo-scope PAT with write access to langbot-app/cla
+          PERSONAL_ACCESS_TOKEN: ${{ secrets.CLA_PAT }}
+        with:
+          path-to-document: 'https://github.com/langbot-app/LangBot/blob/master/CLA.md'
+          remote-organization-name: 'langbot-app'
+          remote-repository-name: 'cla'
+          path-to-signatures: 'signatures/version1/cla.json'
+          branch: 'main'
+          allowlist: 'dependabot[bot],github-actions[bot],devin-ai-integration[bot],Copilot,renovate[bot],bot*'
+          custom-notsigned-prcomment: |
+            Thank you for your contribution! :heart: Before we can merge this pull request, we need you to sign the [LangBot Contributor License Agreement (CLA)](https://github.com/langbot-app/LangBot/blob/master/CLA.md). You keep full copyright of your code — the CLA grants us a license to use and distribute your contribution. Signing takes 10 seconds and covers all repositories in this organization, permanently.
+
+            感谢您的贡献！合并前请阅读并签署[贡献者许可协议（CLA）](https://github.com/langbot-app/LangBot/blob/master/CLA.md)。您保留代码的全部版权，签署仅需回复下方指定内容，一次签署对本组织全部仓库永久有效。
+          custom-allsigned-prcomment: 'All contributors have signed the CLA. :white_check_mark: 所有贡献者均已签署 CLA。'
+          lock-pullrequest-aftermerge: true
+        # SECURITY: this workflow runs on pull_request_target (it holds secrets and has
+        # write access to the base repository). NEVER add an actions/checkout step that
+        # checks out the PR's code here.

{langbot_plugin-0.4.2b4 → langbot_plugin-0.4.3}/AGENTS.md

@@ -816,34 +816,49 @@ Encapsulates plugin instance with:
 
 ### Communication Protocol (`runtime/io/`)
 
-**Action-Based Protocol**:
-- Bidirectional JSON messages
-- Request-response with sequence IDs
-- Streaming support via chunk status
-- File transfer (16KB chunks)
-
-**Action Structure**:
+This protocol is **JSON-RPC 2.0 in all but field names** — a bidirectional, action-based
+RPC carried over a single connection. It is the same shape the Language Server Protocol
+(LSP) and the Model Context Protocol (MCP) use: JSON-RPC 2.0 over stdio / WebSocket, with
+either peer free to initiate calls. We did not adopt the spec verbatim, but the semantics
+map 1:1, and it is useful to think of it that way:
+
+| Our field (`entities/io`)  | JSON-RPC 2.0             | Meaning |
+|----------------------------|--------------------------|---------|
+| `seq_id`                   | `id`                     | Correlates a response back to its request |
+| `action`                   | `method`                 | Which action to invoke |
+| `data` (in a request)      | `params`                 | Call arguments |
+| `data` (in a response)     | `result`                 | Return value (when `code == 0`) |
+| `code` + `message`         | `error.{code,message}`   | `code == 0` is success; non-zero carries the failure in `message` |
+| `chunk_status`             | (MCP-style streaming ext.) | `continue` per chunk, `end` closes a streamed response |
+
+Both peers share one connection and may call each other's actions. Requests and responses
+are told apart by shape: a message carrying `action` is an inbound request, one carrying
+`code` is a response. Each side allocates `seq_id` from its own incrementing counter, so the
+two id spaces are dispatched independently and never collide.
+
+**Request** (`ActionRequest`, `entities/io/req.py`):
 ```json
-{
-  "action": "action_name",
-  "seq": 12345,
-  "data": {...},
-  "chunk_status": "start|continue|end"
-}
+{ "seq_id": 12345, "action": "action_name", "data": {} }
 ```
 
-**Response Structure**:
+**Response** (`ActionResponse`, `entities/io/resp.py`):
 ```json
-{
-  "seq": 12345,
-  "ok": true,
-  "data": {...}
-}
+{ "seq_id": 12345, "code": 0, "message": "success", "data": {}, "chunk_status": "continue" }
 ```
 
-**Transport Implementations**:
-- `StdioHandler`: stdin/stdout communication
-- `WebSocketHandler`: WebSocket client/server
+- `code == 0` → success, payload in `data`; non-zero → error, human-readable text in `message`.
+- **Streaming**: the responder emits N chunks with `chunk_status: "continue"`, then a final
+  `chunk_status: "end"` (consumed by `Handler.call_action_generator`).
+- **File transfer**: large blobs travel as `__file_chunk` actions — 16KB base64 chunks,
+  reassembled to `data/temp/lbp/<file_key>` on the receiving side.
+
+**Core engine**: `runtime/io/handler.py` (`Handler`) owns `seq_id` allocation, the
+`resp_waiters` (single response) and `resp_queues` (streamed response) correlation maps,
+timeouts, and the receive loop (`Handler.run`).
+
+**Transport Implementations** (`Connection` subclasses, `runtime/io/connections/`):
+- `stdio.py`: stdin/stdout — default for subprocess (personal / lightweight) plugins
+- `ws.py`: WebSocket — for containerized / remote plugin deployments
 
 ## CLI Tools
 
@@ -946,6 +961,15 @@ Box selects the first available sandbox backend among **Docker / nsjail / E2B**.
 
 To make LangBot connect to a standalone Box runtime (mirrors the plugin-runtime flow): in LangBot's `data/config.yaml` set `box.runtime.endpoint` to the runtime's base URL (e.g. `ws://127.0.0.1:5410`), pick `box.backend` (`'local'`/`'docker'`/`'nsjail'`/`'e2b'`), and start LangBot with `--standalone-box`. In Docker deployments LangBot reaches the Box runtime at host `langbot_box:5410`.
 
+#### nsjail backend in containers — cgroup namespace requirement
+
+The official `docker/docker-compose.yaml` runs the Box container with the **Docker (docker.sock) backend**, which has no cgroup requirements. The **nsjail backend** is different and has a non-obvious deployment requirement when run inside a container (e.g. a per-pod Box sidecar, or `BOX__BACKEND=nsjail`):
+
+- nsjail with cgroup v2 limits (`--use_cgroupv2`) creates a child cgroup and enables controllers by writing `+memory`/`+pids`/`+cpu` to the cgroup root's `cgroup.subtree_control`. Inside a **private cgroup namespace** (Docker/k8s default) the container's own cgroup root already holds live processes (the Box runtime itself), so the kernel's *no-internal-process* rule rejects that write with **EBUSY** and every sandbox launch aborts with **exit 255**.
+- **Fix: run the Box container in the host cgroup namespace** — compose `cgroup: host` (or `docker run --cgroupns=host`), plus `privileged: true` (nsjail also needs clone-namespaces/chroot). Then `_detect_cgroup_v2()` succeeds and nsjail applies precise cgroup memory/pid/cpu caps.
+- `NsjailBackend._detect_cgroup_v2()` probes the **authoritative** operation (a real `cgroup.subtree_control` write), not just a `mkdir` under the cgroup root — a mkdir probe false-positives in a private cgroupns because mkdir succeeds while the subtree_control write later EBUSYs.
+- **Without cgroups there is no hard memory cap.** When cgroup v2 is unavailable the backend falls back to rlimits but **deliberately does NOT set `--rlimit_as`**: RLIMIT_AS limits *virtual* address space, which `uv`/`node`/Rust/JVM reserve in gigabytes, so a small RLIMIT_AS aborts them instantly (`memory allocation of N bytes failed`, exit 255) — this is what silently broke uvx-based stdio MCP servers. There is no RSS-based rlimit on modern Linux, so accurate memory capping **requires** cgroups (host cgroupns) or a container-level memory limit (compose `mem_limit`). The rlimit fallback still applies safe caps (pids/fsize/nofile).
+
 ### Plugin development loop
 
 ```bash

langbot_plugin-0.4.3/CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing to langbot-plugin-sdk
+
+Thank you for your interest in contributing! For general contribution guidelines, please refer to the [LangBot contribution guide](https://github.com/langbot-app/LangBot/blob/master/CONTRIBUTING.md).
+
+感谢您有意参与贡献！通用贡献指引请参阅 [LangBot 贡献指南](https://github.com/langbot-app/LangBot/blob/master/CONTRIBUTING.md)。
+
+## Contributor License Agreement (CLA)
+
+To protect the project and every contributor, we require all code contributors to sign the [LangBot Contributor License Agreement](https://github.com/langbot-app/LangBot/blob/master/CLA.md). You keep full copyright of your code — the CLA only grants us a license to use and distribute your contribution.
+
+Signing takes 10 seconds: when you open your first PR, a bot will guide you to reply with a single comment. One signature covers all repositories in this organization, permanently.
+
+为了保护项目和每一位贡献者，我们要求所有代码贡献者签署 [LangBot 贡献者许可协议（CLA）](https://github.com/langbot-app/LangBot/blob/master/CLA.md)。您保留自己代码的全部版权，CLA 仅授予项目使用、分发您贡献的许可。
+
+签署只需 10 秒：首次提交 PR 时，机器人会自动评论提示，按提示回复一句话即完成签署，此后对本组织所有仓库永久有效。

{langbot_plugin-0.4.2b4 → langbot_plugin-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langbot-plugin
-Version: 0.4.2b4
+Version: 0.4.3
 Summary: This package contains the SDK, CLI for building plugins for LangBot, plus the runtime for hosting LangBot plugins
 Project-URL: Homepage, https://langbot.app
 Project-URL: Repository, https://github.com/langbot-app/langbot-plugin-sdk
@@ -14,6 +14,7 @@ Requires-Dist: dotenv>=0.9.9
 Requires-Dist: e2b>=2.15
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: jinja2>=3.1.6
+Requires-Dist: packaging>=24.0
 Requires-Dist: pip>=25.2
 Requires-Dist: pydantic-settings>=2.10.1
 Requires-Dist: pydantic>=2.11.5

{langbot_plugin-0.4.2b4 → langbot_plugin-0.4.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langbot-plugin"
-version = "0.4.2b4"
+version = "0.4.3"
 description = "This package contains the SDK, CLI for building plugins for LangBot, plus the runtime for hosting LangBot plugins"
 readme = "README.md"
 authors = [
@@ -14,6 +14,7 @@ dependencies = [
     "e2b>=2.15",
     "httpx>=0.28.1",
     "jinja2>=3.1.6",
+    "packaging>=24.0",
     "pip>=25.2",
     "pydantic>=2.11.5",
     "pydantic-settings>=2.10.1",

langbot_plugin-0.4.3/src/langbot_plugin/assets/templates/.github/workflows/release.yml.example

@@ -0,0 +1,77 @@
+{% raw %}name: Release Plugin
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - "manifest.yaml"
+  workflow_dispatch:
+    inputs:
+      release:
+        description: "Create a new release"
+        required: true
+        type: boolean
+        default: true
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install lbp CLI
+        run: pip install langbot-plugin
+
+      - name: Get metadata
+        id: meta
+        run: |
+          PLUGIN_NAME=$(grep -m1 'name:' manifest.yaml | awk '{print $2}' | tr -d '"'"'"'')
+          VERSION=$(grep -m1 'version:' manifest.yaml | awk '{print $2}' | tr -d '"'"'"'')
+          AUTHOR=$(grep -m1 'author:' manifest.yaml | awk '{print $2}' | tr -d '"'"'"'')
+          echo "name=$PLUGIN_NAME" >> "$GITHUB_OUTPUT"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=v$VERSION" >> "$GITHUB_OUTPUT"
+          echo "artifact=${AUTHOR}-${PLUGIN_NAME}-${VERSION}" >> "$GITHUB_OUTPUT"
+
+      - name: Check release exists
+        id: check
+        run: |
+          if gh release view "$TAG" --json tagName > /dev/null 2>&1; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ steps.meta.outputs.tag }}
+
+      - name: Build plugin
+        if: steps.check.outputs.exists == 'false'
+        run: lbp build -o dist
+
+      - name: Create release
+        if: steps.check.outputs.exists == 'false'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.meta.outputs.tag }}
+          name: ${{ steps.meta.outputs.artifact }}
+          body: |
+            ## ${{ steps.meta.outputs.artifact }}
+
+            ### Installation
+            Download `${{ steps.meta.outputs.artifact }}.lbpkg` and install via LangBot plugin marketplace.
+          files: dist/${{ steps.meta.outputs.artifact }}.lbpkg
+          draft: false
+          prerelease: false
+{% endraw %}

langbot_plugin-0.4.3/src/langbot_plugin/assets/templates/README.md.example

@@ -0,0 +1,15 @@
+# {{ plugin_name }}
+
+{{ plugin_description }}
+
+## Installation
+
+Install this plugin via the LangBot plugin marketplace.
+
+## Configuration
+
+Configure the plugin parameters in the LangBot admin panel.
+
+## Usage
+
+<!-- TODO: Add usage instructions for your plugin here -->

langbot_plugin-0.4.3/src/langbot_plugin/assets/templates/readme/README_zh_Hans.md.example

@@ -0,0 +1,15 @@
+# {{ plugin_name }}
+
+{{ plugin_description }}
+
+## 安装
+
+通过 LangBot 插件市场安装本插件。
+
+## 配置
+
+在 LangBot 管理面板中配置此插件的参数。
+
+## 使用方法
+
+<!-- TODO: 在此添加插件的使用说明 -->

{langbot_plugin-0.4.2b4 → langbot_plugin-0.4.3}/src/langbot_plugin/box/nsjail_backend.py

@@ -110,8 +110,13 @@ class NsjailBackend(BaseSandboxBackend):
         self._cgroup_v2_available = self._detect_cgroup_v2()
         if not self._cgroup_v2_available:
             self.logger.warning(
-                'cgroup v2 not available for nsjail; '
-                'falling back to rlimit-based resource limits'
+                'nsjail cgroup v2 limits unavailable (private cgroup namespace '
+                'or read-only /sys/fs/cgroup); falling back to rlimit-based '
+                'limits WITHOUT a hard memory cap. RLIMIT_AS is intentionally '
+                'not used because it kills uv/node/etc. To enforce a memory '
+                'cap, run the Box container in the host cgroup namespace '
+                '(--cgroupns=host / compose `cgroup: host`) or set a '
+                'container-level memory limit.'
             )
 
         self._base_dir.mkdir(parents=True, exist_ok=True)
@@ -475,16 +480,27 @@ class NsjailBackend(BaseSandboxBackend):
             cpu_ms = int(spec.cpus * 1000)
             args.extend(['--cgroup_cpu_ms_per_sec', str(cpu_ms)])
         else:
-            # rlimit fallback – best-effort. Used whenever the cgroup v2 root is
-            # not writable (the typical containerized case: /sys/fs/cgroup is
-            # mounted read-only), so the sandbox still launches with coarse
-            # resource caps instead of failing outright.
-            # --rlimit_as takes a value in MB (nsjail interprets the bare number
-            # as megabytes), matching spec.memory_mb directly.
-            args.extend(['--rlimit_as', str(spec.memory_mb)])
+            # rlimit fallback – used whenever cgroup v2 delegation is not usable
+            # (private cgroup namespace -> EBUSY, or read-only /sys/fs/cgroup).
+            #
+            # We deliberately do NOT set --rlimit_as for the memory cap.
+            # RLIMIT_AS limits *virtual* address space, not resident memory, and
+            # modern runtimes reserve huge virtual mappings up front: uv/Rust
+            # (and Go/JVM/Node) mmap gigabytes of address space even to do tiny
+            # work, so a 512 MB --rlimit_as aborts them instantly with
+            # "memory allocation of N bytes failed" (exit 255) — which is what
+            # silently broke every uvx-based stdio MCP server in containerized
+            # nsjail deployments. There is no RSS-based rlimit on modern Linux
+            # (RLIMIT_RSS is ignored), so accurate memory capping REQUIRES
+            # cgroups. Operators who need a hard memory cap must run the Box
+            # container in the host cgroup namespace (--cgroupns=host /
+            # compose `cgroup: host`); otherwise bound memory at the container
+            # level (e.g. compose `mem_limit`). We still apply the pid cap,
+            # which is a real rlimit that does not break runtimes.
             args.extend(['--rlimit_nproc', str(spec.pids_limit)])
 
-        # Always set these rlimits regardless of cgroup mode.
+        # Always set these rlimits regardless of cgroup mode. These are safe
+        # for modern runtimes (unlike RLIMIT_AS).
         args.extend(['--rlimit_fsize', '512'])    # max file size 512 MB
         args.extend(['--rlimit_nofile', '256'])    # max open fds
 
@@ -527,42 +543,73 @@ class NsjailBackend(BaseSandboxBackend):
 
     @staticmethod
     def _detect_cgroup_v2() -> bool:
-        """Check whether cgroup v2 is present AND nsjail can create a cgroup.
-
-        nsjail (with ``--use_cgroupv2``) creates its own child cgroup by
-        ``mkdir``-ing directly under the cgroup v2 mount root, then writes to
-        ``cgroup.subtree_control``. Merely detecting a cgroup v2 hierarchy is
-        not enough: inside most containers (Docker/k8s default) ``/sys/fs/cgroup``
-        is mounted **read-only**, so the mkdir fails and the whole sandbox
-        aborts. We must therefore probe real writability — running as root is
-        NOT sufficient, because a read-only bind mount denies root too.
-
-        Returns True only when we can actually create (and remove) a directory
-        under the cgroup v2 root, which is exactly what nsjail needs.
+        """Check whether nsjail's ``--use_cgroupv2`` path will actually work.
+
+        nsjail (with ``--use_cgroupv2``) moves itself into a fresh child cgroup
+        it ``mkdir``s under the cgroup v2 mount root, then enables controllers
+        for that child by writing ``+memory`` (etc.) to the ROOT's
+        ``cgroup.subtree_control``. BOTH operations must succeed.
+
+        Probing ``mkdir`` alone is NOT sufficient and produces a false positive
+        in the common containerized case: inside a **private** cgroup namespace
+        (Docker/k8s default) the container's own cgroup root already contains
+        live processes (the Box runtime itself), so the kernel's
+        "no-internal-process" rule rejects the ``cgroup.subtree_control`` write
+        with ``EBUSY`` even though ``mkdir`` under the root succeeds. nsjail then
+        aborts and every sandbox launch exits 255. Conversely a read-only
+        ``/sys/fs/cgroup`` (another common case) fails the ``mkdir``.
+
+        So we probe the AUTHORITATIVE operation: a real write to
+        ``cgroup.subtree_control``. We only consider it available when that
+        write succeeds, which is exactly nsjail's requirement. Containerized
+        deployments that need cgroup limits must run the Box container in the
+        host cgroup namespace (``--cgroupns=host`` / compose ``cgroup: host``);
+        otherwise this returns False and the backend uses the rlimit fallback.
         """
         cgroup_mount = pathlib.Path('/sys/fs/cgroup')
         if not cgroup_mount.exists():
             return False
         # cgroup v2 has a single hierarchy with a cgroup.controllers file.
         controllers = cgroup_mount / 'cgroup.controllers'
-        if not controllers.exists():
+        subtree_control = cgroup_mount / 'cgroup.subtree_control'
+        if not controllers.exists() or not subtree_control.exists():
             return False
-        # Authoritative writability probe: try to create and remove a throwaway
-        # cgroup directory under the root, mirroring what nsjail does. This
-        # correctly reports False on a read-only /sys/fs/cgroup (the common
-        # containerized case) so the backend falls back to rlimit limits
-        # instead of selecting a cgroup path that is guaranteed to fail.
-        probe = cgroup_mount / f'.langbot-box-probe-{os.getpid()}'
+        # nsjail enables the controllers it needs (memory, pids, cpu) on the
+        # child cgroup, which requires them to be delegated via the root's
+        # subtree_control. Only probe controllers actually present here.
         try:
-            probe.mkdir(mode=0o700)
+            available = set(controllers.read_text().split())
         except Exception:
             return False
-        else:
-            try:
-                probe.rmdir()
-            except Exception:
-                pass
-            return True
+        wanted = [c for c in ('memory', 'pids', 'cpu') if c in available]
+        if not wanted:
+            return False
+        # Authoritative writability probe: re-arm a controller that is already
+        # enabled (idempotent no-op), or briefly toggle one that is not. A
+        # successful write proves nsjail's subtree_control write will also
+        # succeed; EBUSY (private cgroupns) or EACCES/EROFS (read-only mount)
+        # all surface here and correctly select the rlimit fallback.
+        try:
+            enabled = set(subtree_control.read_text().split())
+        except Exception:
+            return False
+        probe_controller = wanted[0]
+        try:
+            if probe_controller in enabled:
+                # Already delegated: re-writing the same enable is a harmless
+                # no-op that still exercises the write permission + EBUSY rule.
+                subtree_control.write_text(f'+{probe_controller}')
+            else:
+                # Not yet delegated: enable then immediately disable to leave
+                # the host configuration untouched.
+                subtree_control.write_text(f'+{probe_controller}')
+                try:
+                    subtree_control.write_text(f'-{probe_controller}')
+                except Exception:
+                    pass
+        except Exception:
+            return False
+        return True
 
     async def _kill_session_processes(self, session_dir: pathlib.Path) -> None:
         """Best-effort kill of nsjail processes associated with a session dir.

{langbot_plugin-0.4.2b4 → langbot_plugin-0.4.3}/src/langbot_plugin/cli/commands/initplugin.py

@@ -155,6 +155,10 @@ def init_plugin_process(
     os.makedirs(assets_dir, exist_ok=True)
     vscode_dir = os.path.join(plugin_dir, ".vscode")
     os.makedirs(vscode_dir, exist_ok=True)
+    readme_dir = os.path.join(plugin_dir, "readme")
+    os.makedirs(readme_dir, exist_ok=True)
+    github_workflows_dir = os.path.join(plugin_dir, ".github", "workflows")
+    os.makedirs(github_workflows_dir, exist_ok=True)
 
     # Create all files from templates
     for file in init_plugin_files:

{langbot_plugin-0.4.2b4 → langbot_plugin-0.4.3}/src/langbot_plugin/cli/gen/renderer.py

@@ -42,11 +42,13 @@ init_plugin_files = [
     "manifest.yaml",
     "main.py",
     "README.md",
+    "readme/README_zh_Hans.md",
     "requirements.txt",
     ".env.example",
     ".gitignore",
     "assets/icon.svg",
     ".vscode/launch.json",
+    ".github/workflows/release.yml",
 ]
 
 

langbot_plugin-0.4.3/src/langbot_plugin/entities/io/errors.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+
+class ConnectionClosedError(Exception):
+    """The connection is closed."""
+
+    def __init__(self, message: str):
+        self.message = message
+
+    def __str__(self):
+        return self.message
+
+
+class ActionCallTimeoutError(Exception):
+    """The action call timed out."""
+
+    def __init__(self, message: str):
+        self.message = message
+
+    def __str__(self):
+        return self.message
+
+
+class DependencyInstallError(Exception):
+    """One or more plugin dependencies failed to install via pip.
+
+    Carries enough structure for callers to log per-package diagnostics or
+    surface them to the UI, instead of a single flattened string.
+    """
+
+    def __init__(
+        self,
+        failed: list[str],
+        plugin: str | None = None,
+        details: dict[str, str] | None = None,
+    ):
+        # List of requirement specs that pip could not install (after retries).
+        self.failed = failed
+        # "<author>/<name>" of the plugin being installed, when known.
+        self.plugin = plugin
+        # Optional per-package error text (requirement spec -> pip stderr tail).
+        self.details = details or {}
+        prefix = f"Plugin {plugin} " if plugin else ""
+        super().__init__(
+            f"{prefix}failed to install {len(failed)} dependencies: {failed}"
+        )
+
+    def __str__(self):
+        prefix = f"Plugin {self.plugin} " if self.plugin else ""
+        return f"{prefix}failed to install {len(self.failed)} dependencies: {self.failed}"
+
+
+class DependencyVerificationError(Exception):
+    """Dependencies were installed but could not be verified afterwards.
+
+    ``missing`` holds requirement specs whose distribution/import could not be
+    resolved after pip reported success; ``version_mismatch`` holds specs whose
+    installed version does not satisfy the requested specifier.
+    """
+
+    def __init__(
+        self,
+        missing: list[str],
+        version_mismatch: list[str] | None = None,
+        plugin: str | None = None,
+    ):
+        self.missing = missing
+        self.version_mismatch = version_mismatch or []
+        self.plugin = plugin
+        prefix = f"Plugin {plugin}: " if plugin else ""
+        super().__init__(
+            f"{prefix}missing dependencies: {missing}, "
+            f"version mismatch: {self.version_mismatch}"
+        )
+
+    def __str__(self):
+        prefix = f"Plugin {self.plugin}: " if self.plugin else ""
+        return (
+            f"{prefix}missing dependencies: {self.missing}, "
+            f"version mismatch: {self.version_mismatch}"
+        )
+
+
+class ActionCallError(Exception):
+    """The action call failed."""
+
+    def __init__(self, message: str):
+        self.message = message
+
+    def __str__(self):
+        return self.message