langbot-plugin 0.4.1__tar.gz → 0.4.2__tar.gz

{langbot_plugin-0.4.1 → langbot_plugin-0.4.2}/AGENTS.md

@@ -1,21 +1,29 @@
 # AGENTS.md
 
-This file is for guiding code agents (like Claude Code, GitHub Copilot, OpenAI Codex, etc.) to work in the langbot-plugin-sdk project.
+This file is for guiding code agents (like Claude Code, GitHub Copilot, OpenAI Codex, etc.) to work in the langbot-plugin-sdk project. `CLAUDE.md` is a symlink to this file.
 
-**IMPORTANT**: This document may contain outdated information and may differ from the actual content. Please refer to the actual situation for accuracy.
+> Always verify specifics (file paths, CLI flags, function signatures) against the actual source before relying on them. When you find this doc out of date, fix it as part of your change.
 
 ## Project Overview
 
 LangBot Plugin SDK is the infrastructure for LangBot's plugin system, providing:
 - **Plugin SDK**: Python APIs and interfaces for plugin development
-- **Plugin Runtime**: Execution environment managing plugin lifecycle
-- **CLI Tools**: `lbp` command for scaffolding, building, and debugging plugins
+- **Plugin Runtime**: Execution environment managing plugin lifecycle (`lbp rt`)
+- **Box Runtime**: Code-sandbox runtime service backing LangBot's Box subsystem (`lbp box`)
+- **CLI Tools**: `lbp` command for scaffolding, building, debugging, and running runtimes
 - **Communication Protocol**: Bidirectional action-based protocol (stdio/WebSocket)
 
-The SDK enables developers to extend LangBot with custom:
-- **Commands**: User-triggered actions (e.g., `!weather tokyo`)
-- **Tools**: LLM-callable functions for AI agents (e.g., web search, database queries)
-- **Event Listeners**: Handlers for message events (e.g., auto-reply, content filtering)
+This SDK is the shared dependency between LangBot and plugins; LangBot pins it as `langbot-plugin==<x.y.z>` in its `pyproject.toml`. The package version lives in this repo's `pyproject.toml`.
+
+The SDK enables developers to extend LangBot with custom components. Six component types are supported (scaffold any of them with `lbp comp <Type>`):
+- **Command**: User-triggered actions (e.g., `!weather tokyo`)
+- **Tool**: LLM-callable functions for AI agents (e.g., web search, database queries)
+- **EventListener**: Handlers for message-pipeline events (e.g., auto-reply, content filtering)
+- **KnowledgeEngine**: Custom knowledge-base retrieval/integration used by RAG
+- **Parser**: Custom parsing of messages/content
+- **Page**: Custom web page embeddable in the LangBot admin panel
+
+Component base classes live in `src/langbot_plugin/api/definition/components/` (`command/`, `tool/`, `common/event_listener.py`, `knowledge_engine/`, `parser/`, `page/`).
 
 ## Technology Stack
 
@@ -47,31 +55,33 @@ langbot-plugin-sdk/
 │   │   │       ├── command/     # CommandReturn
 │   │   │       └── provider/    # Session, Conversation
 │   │   └── proxies/             # API proxy classes
-│   │       ├── langbot_api.py   # LangBotAPIProxy
-│   │       └── query_based.py   # QueryBasedAPIProxy
 │   ├── runtime/                 # Plugin runtime system
-│   │   ├── plugin/              # Plugin management
-│   │   │   ├── mgr.py           # PluginManager
-│   │   │   ├── container.py     # PluginContainer
-│   │   │   └── installer.py    # Plugin installation
+│   │   ├── app.py               # `lbp rt` entrypoint (runtime_app.main)
+│   │   ├── plugin/              # Plugin management (mgr.py, container.py, installer)
 │   │   ├── io/                  # Communication layer
-│   │   │   ├── handler.py       # Action handler
-│   │   │   ├── stdio.py         # Stdio transport
-│   │   │   └── websocket.py    # WebSocket transport
-│   │   └── event/               # Event dispatching
-│   ├── cli/                     # Command-line tools
-│   │   ├── main.py              # lbp entrypoint
-│   │   ├── init.py              # Plugin initialization
-│   │   ├── gen/                 # Component generation
-│   │   └── run.py               # Plugin debugging
+│   │   │   ├── connection.py    # Base connection
+│   │   │   ├── connections/     # stdio / ws connection impls
+│   │   │   ├── controller.py , controllers/   # client/server controllers (stdio, ws)
+│   │   │   ├── handler.py , handlers/          # action handlers
+│   │   └── helper/
+│   ├── box/                     # Box (code-sandbox) runtime — `lbp box`
+│   │   ├── server.py            # `lbp box` entrypoint (box_main)
+│   │   ├── backend.py           # Backend abstraction + selection (Docker handled here/runtime)
+│   │   ├── nsjail_backend.py / e2b_backend.py  # sandbox backend impls
+│   │   ├── runtime.py , client.py , actions.py , models.py , errors.py , security.py , skill_store.py
+│   ├── cli/                     # Command-line tools (`lbp`)
+│   │   ├── __init__.py          # lbp entrypoint + argparse subcommands
+│   │   ├── commands/            # init / comp / build / publish / login / logout impls
+│   │   ├── run/                 # plugin run (remote-debug) impl
+│   │   ├── gen/                 # component generation (Jinja2)
+│   │   ├── i18n.py , locales/   # CLI i18n
+│   │   └── utils/
 │   ├── entities/                # Internal data structures
-│   │   ├── io/                  # Communication protocol
-│   │   └── plugin/              # Plugin metadata
-│   └── utils/                   # Utilities
-│       ├── discover/            # Component discovery
-│       └── network/             # Network helpers
+│   │   └── io/                  # Communication protocol (actions, errors, resp)
+│   ├── assets/templates/        # Plugin scaffolding templates
+│   └── utils/                   # Utilities (discover/, network, log, ...)
 ├── docs/                        # Documentation
-├── pyproject.toml               # Python project config
+├── pyproject.toml               # Python project config (version, requires-python >=3.10)
 └── README.md
 ```
 
@@ -113,12 +123,12 @@ langbot-plugin-sdk/
 
 ```
 BasePlugin
-  ├── Command (1+ per plugin)
-  │   └── Subcommand handlers
-  ├── Tool (0+ per plugin)
-  │   └── call() method
-  └── EventListener (1 per plugin)
-      └── Event handlers
+  ├── Command          → Subcommand handlers
+  ├── Tool             → call() method
+  ├── EventListener    → event handlers
+  ├── KnowledgeEngine  → knowledge-base retrieval/integration (RAG)
+  ├── Parser           → message/content parsing
+  └── Page             → custom admin-panel web page
 ```
 
 ## SDK Development
@@ -806,84 +816,164 @@ 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
 
-### lbp Commands
+### `lbp` Commands
 
 ```bash
-# Initialize new plugin
-lbp init [plugin_name]
+lbp init [plugin_name]            # Scaffold a new plugin
+lbp comp <Command|Tool|EventListener>   # Generate a component
+lbp run [-s]                      # Run/remote-debug the plugin against a running Runtime
+lbp build [-o dist]               # Build the plugin into a zip
+lbp publish [-o dist]             # Publish to LangBot Marketplace (login first: lbp login)
+lbp login [-t TOKEN] / lbp logout # Marketplace account auth
+lbp rt [...]                      # Run the Plugin Runtime (see below)
+lbp box [...]                     # Run the Box (sandbox) Runtime (see below)
+lbp ver                           # Print SDK version
+```
 
-# Generate component
-lbp comp [Command|Tool|EventListener]
+The CLI entrypoint is `src/langbot_plugin/cli/__init__.py` (argparse). `lbp rt` dispatches to `langbot_plugin.runtime.app.main`; `lbp box` dispatches to `langbot_plugin.box.server.main`. Subcommand implementations live under `cli/commands/`, `cli/run/`, and `cli/gen/`.
 
-# Run plugin locally (requires running LangBot)
-lbp run [-s]
+## Debugging the Runtime, CLI & SDK
 
-# Build plugin for distribution
-lbp build
+This is the canonical place for runtime/CLI/box debugging detail (LangBot's own `AGENTS.md` only indexes this section). The corresponding user-facing wiki page is ["调试插件运行时、CLI、SDK"](https://docs.langbot.app/zh/develop/plugin-runtime).
 
-# Publish to marketplace
-lbp publish
+### Recommended workspace layout
+
+Because LangBot depends on entities defined here, clone both repos as siblings under one parent dir and open that parent in your editor:
+
+```
+langbot-projects/
+├── LangBot
+└── langbot-plugin-sdk
+```
+
+Set up LangBot's venv (`cd LangBot && uv sync --dev`) and point your editor's Python interpreter at LangBot's `.venv`.
+
+### Plugin Runtime — `lbp rt`
+
+Start a standalone Plugin Runtime from this repo:
 
-# Start runtime (for WebSocket mode)
-lbp rt
+```bash
+uv run --no-sync lbp rt
+# equivalent: python -m langbot_plugin.cli.__init__ rt
 ```
 
-### Template System (`cli/gen/`)
+`lbp rt` flags (see `cli/__init__.py`):
+
+- `-s`, `--stdio-control`: use stdio for the control connection. **Production only** — in a container LangBot pipes the runtime over stdio.
+- `--ws-control-port` (default `5400`): control port LangBot's main process connects to.
+- `--ws-debug-port` (default `5401`): debug port for `lbp run` to attach a plugin under development.
+- `--debug-only`: do not auto-start plugins in `data/plugins/`; only accept plugins via debug connections.
+- `--skip-deps-check`: skip the per-startup check/install of every installed plugin's dependencies.
+- `--pypi-index-url` / `--pypi-trusted-host`: customize the index used for plugin dependency installs.
 
-- Jinja2-based templates in `assets/templates/`
-- Variables: plugin_name, plugin_author, component_name
-- Generates boilerplate code and manifests
+> **Transport note:** When LangBot is run directly (not in a container), it spawns the runtime itself and talks **stdio**, which **cannot auto-reconnect** — on disconnect it logs "please restart LangBot". A frequent cause is an **orphan runtime** from a previous backend still holding `5400`/`5401`; kill it and restart.
 
-## Testing & Debugging
+### Make LangBot use your locally-modified SDK
 
-### Local Testing
+If you change shared definitions (message entities, plugin data models, etc.), install your local SDK into LangBot's environment so data formats stay compatible at runtime:
 
-1. Start LangBot:
 ```bash
-cd /path/to/LangBot
-uv run main.py
+# In a terminal where LangBot's .venv is ACTIVE, from the langbot-plugin-sdk dir:
+uv pip install .
+```
+
+### Make LangBot connect to your standalone Runtime (WebSocket)
+
+1. In LangBot's `data/config.yaml`, set the control URL:
+
+   ```yaml
+   plugin:
+     runtime_ws_url: ws://localhost:5400/control/ws
+   ```
+
+2. Launch LangBot with `--standalone-runtime` and `--no-sync` (the latter prevents `uv` from overwriting your locally-installed SDK):
+
+   ```bash
+   uv run --no-sync main.py --standalone-runtime
+   ```
+
+   Restart LangBot; it now connects to your `lbp rt` over WebSocket, so you can iterate on the runtime/SDK independently.
+
+### Box Runtime — `lbp box`
+
+The Box Runtime is the sandbox service backing LangBot's `pkg/box` subsystem (`src/langbot_plugin/box/`). Start it with:
+
+```bash
+lbp box                  # WebSocket control transport (default)
+lbp box -s               # stdio control transport
 ```
 
-2. Run plugin:
+`lbp box` flags:
+
+- `--host` (default `0.0.0.0`): bind address.
+- `-s`, `--stdio-control`: use stdio for the control connection (instead of WebSocket).
+- `--ws-control-port` (default `5410`): control port.
+
+All Box WebSocket endpoints share one port (default `5410`): `/rpc/ws` (action RPC control channel) plus managed-process stdio relay endpoints under `/v1/sessions/...`. There is **no** `python -m langbot_plugin.box` launch path — `lbp box` is the only supported entrypoint.
+
+Box selects the first available sandbox backend among **Docker / nsjail / E2B**. Backends live in `box/backend.py`, `box/nsjail_backend.py`, `box/e2b_backend.py`. A common false "no backend" on the LangBot side is Docker running but the user not in the `docker` group (socket permission denied) — that's a host-permissions issue, not a Box bug.
+
+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`.
+
+### Plugin development loop
+
 ```bash
+# 1. Start a LangBot instance (which spawns or connects to a Runtime)
+cd /path/to/LangBot
+uv run main.py
+
+# 2. In your plugin dir, attach it to the Runtime's debug port for live debugging
 cd /path/to/your-plugin
 lbp run
 ```
 
-Plugin connects to LangBot via stdio for testing.
-
-### Debugging Tips
+### Debugging tips
 
 - Use `print()` statements (output to stderr for visibility)
 - Check LangBot logs for plugin errors

{langbot_plugin-0.4.1 → langbot_plugin-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langbot-plugin
-Version: 0.4.1
+Version: 0.4.2
 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.1 → langbot_plugin-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langbot-plugin"
-version = "0.4.1"
+version = "0.4.2"
 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.2/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.2/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.2/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.1 → langbot_plugin-0.4.2}/src/langbot_plugin/box/client.py

@@ -233,6 +233,12 @@ class ActionRPCBoxClient(BoxRuntimeClient):
         data = await self._call(
             LangBotToBoxAction.START_MANAGED_PROCESS,
             {"session_id": session_id, "spec": spec.model_dump(mode="json")},
+            # Starting a managed process can involve a cold dependency bootstrap
+            # (e.g. `uvx <pkg>` downloading the package + interpreter on first
+            # run), which easily exceeds the default 15s action timeout and
+            # caused stdio MCP servers to be torn down mid-install. Give it
+            # headroom so the first launch can complete.
+            timeout=30.0,
         )
         return BoxManagedProcessInfo.model_validate(data)
 

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

@@ -44,6 +44,23 @@ _READONLY_ETC_ENTRIES: list[str] = [
     '/etc/resolv.conf',  # needed when network=ON
 ]
 
+# Essential character devices bind-mounted into the sandbox's /dev.
+# /dev is a fresh empty tmpfs (see _build_args), so these nodes do not exist
+# unless we bind them in from the host. Tooling that shells out for probes
+# relies on them — notably `uv`/`uvx` redirects its glibc/musl detection
+# subprocess to /dev/null; without it uv fails with "Could not detect either
+# glibc version nor musl libc version" and the process exits before it can do
+# anything (e.g. an stdio MCP server dies before the initialize handshake,
+# surfacing as a misleading "Connection closed / please check URL").
+_DEV_NODES: list[str] = [
+    '/dev/null',
+    '/dev/zero',
+    '/dev/full',
+    '/dev/random',
+    '/dev/urandom',
+    '/dev/tty',
+]
+
 _DEFAULT_BASE_DIR = '/tmp/langbot-box-nsjail'
 
 
@@ -116,6 +133,19 @@ class NsjailBackend(BaseSandboxBackend):
         for d in (root_dir, workspace_dir, tmp_dir, home_dir):
             d.mkdir(parents=True, exist_ok=True)
 
+        # When a host_path is mounted into the sandbox it becomes the nsjail
+        # bind-mount source (see _build_mounts). nsjail requires the source to
+        # already exist on the host, otherwise the bind-mount fails and the
+        # command exits 255 with no stdout/stderr. The per-session loop above
+        # never creates host_path (it lives outside session_dir), so ensure it
+        # exists here. Read-only mounts intentionally are NOT auto-created: a
+        # missing read-only source is a caller error that should surface.
+        if (
+            spec.host_path is not None
+            and spec.host_path_mode == BoxHostMountMode.READ_WRITE
+        ):
+            os.makedirs(spec.host_path, exist_ok=True)
+
         # If host_path is specified, we will use it directly instead of the
         # per-session workspace when building nsjail args (see _build_mounts).
         meta = {
@@ -317,6 +347,15 @@ class NsjailBackend(BaseSandboxBackend):
         args.extend(['--mount', 'none:/proc:proc:rw'])
         args.extend(['--mount', 'none:/dev:tmpfs:rw'])
 
+        # /dev is a fresh empty tmpfs, so bind in the essential character
+        # devices. Without /dev/null in particular, uv's glibc/musl detection
+        # subprocess fails and any uvx-launched process (e.g. stdio MCP servers)
+        # exits before doing useful work. Mounted read-write so writes to
+        # /dev/null behave normally.
+        for dev in _DEV_NODES:
+            if os.path.exists(dev):
+                args.extend(['--bindmount', f'{dev}:{dev}'])
+
         # Working directory.
         args.extend(['--cwd', spec.workdir])
 
@@ -424,14 +463,24 @@ class NsjailBackend(BaseSandboxBackend):
         args: list[str] = []
 
         if self._cgroup_v2_available:
-            # cgroup v2 – precise limits.
+            # cgroup v2 – precise limits. nsjail defaults to the legacy cgroup
+            # v1 layout, so we MUST opt into v2 explicitly; without this flag
+            # nsjail tries to mkdir under /sys/fs/cgroup/<controller>/... (v1
+            # paths) and aborts on a v2-only host. The writability of the v2
+            # root is already verified in _detect_cgroup_v2().
+            args.append('--use_cgroupv2')
             memory_bytes = spec.memory_mb * 1024 * 1024
             args.extend(['--cgroup_mem_max', str(memory_bytes)])
             args.extend(['--cgroup_pids_max', str(spec.pids_limit)])
             cpu_ms = int(spec.cpus * 1000)
             args.extend(['--cgroup_cpu_ms_per_sec', str(cpu_ms)])
         else:
-            # rlimit fallback – best-effort.
+            # 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)])
             args.extend(['--rlimit_nproc', str(spec.pids_limit)])
 
@@ -478,25 +527,42 @@ class NsjailBackend(BaseSandboxBackend):
 
     @staticmethod
     def _detect_cgroup_v2() -> bool:
-        """Check whether the host runs cgroup v2 and we can write to it."""
+        """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.
+        """
         cgroup_mount = pathlib.Path('/sys/fs/cgroup')
         if not cgroup_mount.exists():
             return False
-        # cgroup v2 has a single hierarchy with cgroup.controllers file.
+        # cgroup v2 has a single hierarchy with a cgroup.controllers file.
         controllers = cgroup_mount / 'cgroup.controllers'
         if not controllers.exists():
             return False
-        # Check if we can write to a cgroup subtree (needed for nsjail).
-        # A rough heuristic: if the user owns a cgroup directory we're probably
-        # running under systemd user delegation.
-        user_slice = cgroup_mount / f'user.slice/user-{os.getuid()}.slice'
-        if user_slice.exists() and os.access(user_slice, os.W_OK):
-            return True
-        # If running as root (uid 0), cgroup v2 is always usable.
-        if os.getuid() == 0:
+        # 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()}'
+        try:
+            probe.mkdir(mode=0o700)
+        except Exception:
+            return False
+        else:
+            try:
+                probe.rmdir()
+            except Exception:
+                pass
             return True
-        # Conservative: if we can't confirm writability, report unavailable.
-        return False
 
     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.1 → langbot_plugin-0.4.2}/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.1 → langbot_plugin-0.4.2}/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",
 ]