langbot-plugin 0.4.6__tar.gz → 0.4.7__tar.gz

langbot_plugin-0.4.7/AGENTS.md

@@ -0,0 +1,121 @@
+# AGENTS.md
+
+This file guides code agents working in the `langbot-plugin-sdk` repository. `CLAUDE.md` is a symlink to this file.
+
+Read `ARCHITECTURE.md` before non-trivial SDK, CLI, Plugin Runtime, Box Runtime, protocol, or cross-repo LangBot changes. This file is the working checklist; `ARCHITECTURE.md` is the system map.
+
+## Quick Facts
+
+- Package name: `langbot-plugin`.
+- Python: `>=3.10`.
+- CLI entrypoint: `lbp = langbot_plugin.cli:main`.
+- Main consumers: LangBot main repo and third-party plugins.
+- Runtime license: `src/langbot_plugin/runtime/` is AGPL; the rest is Apache 2.0.
+- LangBot pins this package in its `pyproject.toml`; local cross-repo testing needs a local install into LangBot's venv.
+
+## Essential Commands
+
+```bash
+uv sync --dev
+uv run lbp --help
+uv run lbp ver
+uv run lbp init MyPlugin
+uv run lbp comp Command
+uv run lbp run
+uv run lbp build
+uv run lbp publish
+uv run lbp rt
+uv run lbp box
+```
+
+Focused validation:
+
+```bash
+uv run pytest tests/api -q
+uv run pytest tests/cli -q
+uv run pytest tests/runtime -q
+uv run pytest tests/box -q
+uv run pytest tests/packaging/test_installed_cli_blackbox.py -q
+uv run python scripts/check_action_consistency.py
+```
+
+## Where to Look
+
+- Architecture map: `ARCHITECTURE.md`.
+- CLI entrypoint and flags: `src/langbot_plugin/cli/__init__.py`.
+- Plugin SDK APIs: `src/langbot_plugin/api/`.
+- Plugin Runtime: `src/langbot_plugin/runtime/`.
+- Box Runtime: `src/langbot_plugin/box/`.
+- Action protocol: `src/langbot_plugin/entities/io/` and `src/langbot_plugin/runtime/io/handler.py`.
+- Plugin tutorial: https://docs.langbot.app/zh/plugin/dev/tutor.
+- Runtime/CLI/SDK debugging: https://docs.langbot.app/zh/develop/plugin-runtime.
+- LangBot main repo: `../LangBot/`.
+
+## Cross-Repo LangBot Testing
+
+Use sibling repos:
+
+```text
+langbot-projects/
+├── LangBot/
+└── langbot-plugin-sdk/
+```
+
+When changing shared entities, component contracts, action payloads, Plugin Runtime, or Box Runtime:
+
+```bash
+# from langbot-plugin-sdk, with LangBot's .venv active
+uv pip install .
+
+# from LangBot; keep local SDK installed
+uv run --no-sync main.py
+```
+
+Standalone runtime flows:
+
+```bash
+# Plugin Runtime, default control :5400 and debug :5401
+uv run --no-sync lbp rt
+
+# Box Runtime, default :5410
+uv run --no-sync lbp box
+```
+
+Then configure LangBot as needed:
+
+- Plugin runtime: `plugin.runtime_ws_url: ws://localhost:5400/control/ws`, launch LangBot with `--standalone-runtime`.
+- Box runtime: `box.runtime.endpoint: ws://127.0.0.1:5410`, choose `box.backend`, launch LangBot with `--standalone-box`.
+
+## Change Rules
+
+- Treat action enums and Pydantic models as cross-process API contracts; update callers, handlers, and tests together.
+- Do not duplicate action strings outside the enum definitions.
+- Keep generated plugin templates, component base classes, CLI renderer behavior, and docs consistent when component contracts change.
+- Preserve `uv run --no-sync` guidance for local SDK testing; otherwise LangBot may reinstall the pinned PyPI package.
+- Keep comments/docstrings in English and user-facing labels/descriptions i18n-ready.
+- Commit message format: `<type>(<scope>): <subject>`.
+
+## Runtime Pitfalls
+
+- Direct local LangBot runs often spawn Plugin Runtime over stdio; stdio disconnects cannot auto-reconnect.
+- Orphan Runtime processes holding `5400`/`5401` commonly break `lbp run` debugging.
+- Docker deployments use `langbot_plugin_runtime:5400/control/ws` and `langbot_box:5410` as service hosts.
+- A false Box “no backend” often means Docker socket permission is missing, not that Docker is unavailable.
+- nsjail inside containers needs host cgroup namespace for cgroup v2 limits; do not fake memory limits with `RLIMIT_AS` because it breaks tools that reserve large virtual memory.
+- There is no supported `python -m langbot_plugin.box` entrypoint; use `lbp box`.
+- `CLAUDE.md` is a symlink to this file; edit `AGENTS.md`, not the symlink.
+
+## Principles
+
+- Keep it simple, stupid.
+- Entities should not be multiplied unnecessarily.
+- 八荣八耻
+
+    以瞎猜接口为耻，以认真查询为荣。
+    以模糊执行为耻，以寻求确认为荣。
+    以臆想业务为耻，以人类确认为荣。
+    以创造接口为耻，以复用现有为荣。
+    以跳过验证为耻，以主动测试为荣。
+    以破坏架构为耻，以遵循规范为荣。
+    以假装理解为耻，以诚实无知为荣。
+    以盲目修改为耻，以谨慎重构为荣。

langbot_plugin-0.4.7/ARCHITECTURE.md

@@ -0,0 +1,225 @@
+# Architecture
+
+This document maps the `langbot-plugin-sdk` repository. It explains the durable structure and cross-process contracts. For working rules, commands, and pitfalls, see `AGENTS.md`.
+
+## What This Repository Is
+
+`langbot-plugin-sdk` is the infrastructure package behind LangBot's plugin and sandbox systems. It is published to PyPI as `langbot-plugin` and pinned by the LangBot main repo.
+
+The package has four roles:
+
+- **Plugin SDK**: public APIs and entities imported by plugin authors.
+- **CLI**: `lbp`, used to scaffold, run, debug, build, publish, and launch runtimes.
+- **Plugin Runtime**: `lbp rt`, the host process that manages plugin packages and plugin processes.
+- **Box Runtime**: `lbp box`, the sandbox runtime used by LangBot's Box subsystem.
+
+The runtime code under `src/langbot_plugin/runtime/` is AGPL; the rest of the repo is Apache 2.0.
+
+## Repository Boundary
+
+This repo is coupled to LangBot but owns different things.
+
+- The LangBot main repo owns product behavior, HTTP API, web UI, platform adapters, pipeline execution, model/tool orchestration, persistence, skills integration, and the LangBot-side runtime connectors.
+- This SDK repo owns plugin author APIs, shared message/event/context entities, the action RPC protocol, `lbp`, Plugin Runtime implementation, and Box Runtime implementation.
+- Plugins import this package directly; LangBot also imports it for shared entities and runtime protocols.
+
+If a change alters shared entities, component contracts, action names/payloads, runtime behavior, or Box models, update/test both repos in lockstep.
+
+## Top-Level Layout
+
+```text
+langbot-plugin-sdk/
+├── src/langbot_plugin/
+│   ├── api/                  # Public plugin-author SDK
+│   │   ├── definition/       # BasePlugin, components, manifests
+│   │   ├── entities/         # Contexts, events, builtin platform/provider models
+│   │   └── proxies/          # APIs exposed to plugin code
+│   ├── cli/                  # `lbp` entrypoint and subcommands
+│   ├── runtime/              # Plugin Runtime (`lbp rt`)
+│   ├── box/                  # Box Runtime (`lbp box`)
+│   ├── entities/io/          # Action RPC request/response/error/action models
+│   ├── assets/               # Scaffolding templates and page SDK asset
+│   └── utils/
+├── docs/                     # Supplemental protocol/component docs
+├── tests/                    # Unit and black-box tests
+├── pyproject.toml
+└── README.md
+```
+
+## Public Plugin SDK
+
+Plugin-facing APIs live under `src/langbot_plugin/api/`.
+
+- `definition/plugin.py` defines `BasePlugin`.
+- `definition/components/` defines component base classes.
+- `definition/components/manifest.py` defines component manifest models.
+- `entities/` defines event/context/message/provider data models passed across LangBot, runtime, and plugin code.
+- `proxies/` defines methods plugins can call back into LangBot, such as messaging, storage, model invocation, tools, RAG, parser, and query-scoped APIs.
+
+Plugins extend LangBot through six component types:
+
+- `Command`
+- `Tool`
+- `EventListener`
+- `KnowledgeEngine`
+- `Parser`
+- `Page`
+
+The CLI scaffolds components via `lbp comp <Type>`. Component templates live under `src/langbot_plugin/assets/templates/`; generation logic lives under `src/langbot_plugin/cli/gen/`.
+
+## CLI Architecture
+
+`lbp` is declared in `pyproject.toml` and enters at `src/langbot_plugin/cli:main`, implemented by `src/langbot_plugin/cli/__init__.py`.
+
+Subcommands:
+
+- `init`: scaffold a plugin project.
+- `comp`: generate a plugin component.
+- `run`: run/remote-debug a plugin against a Runtime debug server.
+- `build`: package a plugin zip.
+- `publish`: publish a plugin to the marketplace.
+- `login` / `logout`: marketplace authentication.
+- `rt`: launch the Plugin Runtime.
+- `box`: launch the Box Runtime.
+- `ver`: print package version.
+
+Subcommand implementations live under `cli/commands/`, `cli/run/`, and `cli/gen/`. CLI i18n lives under `cli/locales/`.
+
+## Action RPC Protocol
+
+The runtime protocol is a bidirectional action RPC protocol over stdio or WebSocket. It is implemented by `runtime/io/handler.py` and data models under `entities/io/`.
+
+Request shape:
+
+```json
+{ "seq_id": 1, "action": "action_name", "data": {} }
+```
+
+Response shape:
+
+```json
+{ "seq_id": 1, "code": 0, "message": "success", "data": {}, "chunk_status": "continue" }
+```
+
+Core mechanics:
+
+- `seq_id` correlates responses to requests.
+- Messages with `action` are requests; messages with `code` are responses.
+- Each peer may initiate requests on the same connection.
+- `Handler.call_action()` waits for one response.
+- `Handler.call_action_generator()` consumes streamed responses.
+- Streaming emits `chunk_status: "continue"` chunks and ends with `"end"`.
+- File transfer uses `CommonAction.FILE_CHUNK` with 16KB base64 chunks stored under `data/temp/lbp/`.
+
+Action enums are the protocol contract:
+
+- `CommonAction`
+- `PluginToRuntimeAction`
+- `RuntimeToPluginAction`
+- `LangBotToRuntimeAction`
+- `RuntimeToLangBotAction`
+- `LangBotToBoxAction`
+
+Do not duplicate action strings outside these enums.
+
+## Plugin Runtime
+
+`lbp rt` enters `runtime/app.py::main()` and builds `RuntimeApplication`.
+
+Runtime graph:
+
+```text
+LangBot PluginRuntimeConnector
+  ↔ control connection
+  ↔ RuntimeApplication
+  → PluginManager
+  → PluginContainer(s)
+  ↔ PluginConnectionHandler(s)
+  ↔ plugin process(es)
+```
+
+Important modules:
+
+- `runtime/app.py`: selects stdio vs WebSocket control transport, starts control/debug servers, launches plugin manager tasks.
+- `runtime/context.py`: shared runtime context object.
+- `runtime/settings.py`: runtime settings, including marketplace/cloud URL.
+- `runtime/plugin/mgr.py`: plugin discovery, installation, dependency checks, launch, shutdown, event/tool/command/RAG/page dispatch.
+- `runtime/plugin/container.py`: loaded plugin package, manifest, component containers, status.
+- `runtime/io/handlers/control.py`: actions LangBot calls on the Runtime.
+- `runtime/io/handlers/plugin.py`: actions the Runtime calls on plugin processes.
+- `runtime/io/controllers/`: stdio/WebSocket server and client controllers.
+- `runtime/io/connections/`: transport-specific connection implementations.
+
+The Runtime has two external channels:
+
+- **control channel**: LangBot ↔ Runtime, stdio or `:5400/control/ws` by default.
+- **debug channel**: plugin dev process ↔ Runtime, WebSocket `:5401/plugin/debug/ws` by default.
+
+Installed plugins are stored under `data/plugins/{author}__{name}`. Runtime plugin processes normally run as separate Python processes and connect back via stdio or debug WebSocket.
+
+## Box Runtime
+
+`lbp box` enters `box/server.py::main()` and serves `BoxRuntime` through action RPC.
+
+Box graph:
+
+```text
+LangBot BoxService
+  ↔ BoxRuntimeConnector
+  ↔ BoxServerHandler
+  → BoxRuntime
+  → Backend session(s)
+  → Docker/Podman, nsjail, or E2B sandbox
+```
+
+Important modules:
+
+- `box/server.py`: CLI entrypoint, aiohttp WebSocket routes, `BoxServerHandler` action registration.
+- `box/runtime.py`: session lifecycle, per-session locks, TTL cleanup, command execution, managed processes.
+- `box/models.py`: `BoxSpec`, execution results, managed-process specs.
+- `box/client.py`: action-RPC client used by LangBot-side connector/service.
+- `box/actions.py`: `LangBotToBoxAction` enum.
+- `box/backend.py`: backend abstraction and local backend selection.
+- `box/nsjail_backend.py`: nsjail backend.
+- `box/e2b_backend.py`: E2B backend.
+- `box/skill_store.py`: Box-owned skill package CRUD and install/preview helpers.
+- `box/security.py`: path/security helper logic.
+
+Default Box WebSocket endpoints on port `5410`:
+
+- `/rpc/ws`: action RPC control channel.
+- `/v1/sessions/{session_id}/managed-process/ws`: legacy default process stdio relay.
+- `/v1/sessions/{session_id}/managed-process/{process_id}/ws`: named process stdio relay.
+
+There is no supported `python -m langbot_plugin.box` entrypoint; use `lbp box`.
+
+## Backend Selection
+
+Box can execute through multiple sandbox backends:
+
+- Docker/Podman through the local CLI backend path.
+- nsjail for local Linux sandboxing.
+- E2B for remote cloud sandboxes.
+
+LangBot sends Box config during initialization. Backend selection is controlled by LangBot's `box.backend` config (`local`, `docker`, `nsjail`, `e2b`) and the Box runtime's backend availability probes.
+
+A false “no backend” often means Docker exists but the user cannot access the Docker socket. nsjail inside containers requires host cgroup namespace for cgroup v2 limits if hard memory/pid/cpu enforcement is expected.
+
+## Cross-Repo Development Flow
+
+When changing shared contracts:
+
+1. Change this SDK repo first or in the same branch set.
+2. Install the local SDK into LangBot's virtualenv: `uv pip install .` from this repo while LangBot's `.venv` is active.
+3. Run LangBot with `uv run --no-sync ...` so `uv` does not replace the local SDK with the pinned PyPI package.
+4. Exercise the exact path changed: plugin stdio, plugin WebSocket, `lbp run`, `lbp rt`, `lbp box`, Box WebSocket, or Box stdio.
+
+The SDK `AGENTS.md` keeps the short command checklist; this file keeps the structural map.
+
+## Design Biases
+
+- Keep plugin-author SDK APIs stable and explicit.
+- Treat action enums and Pydantic models as cross-process API contracts.
+- Keep runtime process management separate from LangBot product logic.
+- Keep Box sandbox semantics in `box/`; LangBot should call Box through the service/client protocol.
+- Prefer tests around protocol shape and black-box CLI behavior when changing runtime boundaries.

{langbot_plugin-0.4.6 → langbot_plugin-0.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langbot-plugin
-Version: 0.4.6
+Version: 0.4.7
 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

{langbot_plugin-0.4.6 → langbot_plugin-0.4.7}/docs/communication/apis/lb2rt.md

@@ -39,13 +39,34 @@
 ### Request
 
 ```json
+{
+    "event_context": {},
+    "include_plugins": ["author/name"]
+}
 ```
 
 ### Response
 
 ```json
+{
+    "emitted_plugins": [],
+    "response_sources": [
+        {
+            "kind": "reply_message_chain",
+            "plugin": {
+                "author": "plugin_author",
+                "name": "plugin_name"
+            }
+        }
+    ],
+    "event_context": {}
+}
 ```
 
+`emitted_plugins` contains plugins whose event handlers ran. `response_sources`
+contains plugins that changed a deferred response field on the event context, such
+as `reply_message_chain`.
+
 ## `list_tools`
 
 ### Request
@@ -68,4 +89,4 @@
 ### Response
 
 ```json
-```
+```

{langbot_plugin-0.4.6 → langbot_plugin-0.4.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langbot-plugin"
-version = "0.4.6"
+version = "0.4.7"
 description = "This package contains the SDK, CLI for building plugins for LangBot, plus the runtime for hosting LangBot plugins"
 readme = "README.md"
 authors = [

{langbot_plugin-0.4.6 → langbot_plugin-0.4.7}/src/langbot_plugin/api/entities/builtin/command/errors.py

@@ -5,7 +5,6 @@ class CommandError(pydantic.BaseModel):
     message: str
 
     def __init__(self, message: str):
-
         super().__init__(message=message)
 
     def __str__(self):

{langbot_plugin-0.4.6 → langbot_plugin-0.4.7}/src/langbot_plugin/box/backend.py

@@ -5,6 +5,7 @@ import asyncio
 import dataclasses
 import datetime as dt
 import logging
+import os
 import re
 import shlex
 import shutil
@@ -26,6 +27,7 @@ from .security import validate_sandbox_security
 # produce large output within the time limit.  After this many bytes the
 # remaining output is discarded before decoding.
 _MAX_RAW_OUTPUT_BYTES = 1_048_576  # 1 MB per stream
+_FALSE_VALUES = {"0", "false"}
 
 
 @dataclasses.dataclass(slots=True)
@@ -80,6 +82,7 @@ class CLISandboxBackend(BaseSandboxBackend):
         super().__init__(logger)
         self.command = command
         self.name = backend_name
+        self.cpu_limit_enabled = True
 
     async def is_available(self) -> bool:
         if shutil.which(self.command) is None:
@@ -121,16 +124,14 @@ class CLISandboxBackend(BaseSandboxBackend):
         if spec.network == BoxNetworkMode.OFF:
             args.extend(["--network", "none"])
 
-        # Resource limits
-        args.extend(["--cpus", str(spec.cpus)])
-        args.extend(["--memory", f"{spec.memory_mb}m"])
-        args.extend(["--pids-limit", str(spec.pids_limit)])
+        args.extend(self._build_resource_limit_args(spec))
 
         if spec.read_only_rootfs:
             args.append("--read-only")
             args.extend(["--tmpfs", "/tmp:size=64m"])
 
         if spec.host_path is not None and spec.host_path_mode != BoxHostMountMode.NONE:
+            os.makedirs(spec.host_path, exist_ok=True)
             mount_spec = (
                 f"{spec.host_path}:{spec.mount_path}:{spec.host_path_mode.value}"
             )
@@ -149,7 +150,8 @@ class CLISandboxBackend(BaseSandboxBackend):
             f"session_id={spec.session_id} container_name={container_name} "
             f"image={spec.image} network={spec.network.value} "
             f"host_path={spec.host_path} host_path_mode={spec.host_path_mode.value} mount_path={spec.mount_path} "
-            f"cpus={spec.cpus} memory_mb={spec.memory_mb} pids_limit={spec.pids_limit} "
+            f"cpus={spec.cpus} cpu_limit_enabled={self.cpu_limit_enabled} "
+            f"memory_mb={spec.memory_mb} pids_limit={spec.pids_limit} "
             f"read_only_rootfs={spec.read_only_rootfs} workspace_quota_mb={spec.workspace_quota_mb}"
         )
 
@@ -333,6 +335,14 @@ class CLISandboxBackend(BaseSandboxBackend):
         suffix = uuid.uuid4().hex[:8]
         return f"langbot-box-{normalized[:32]}-{suffix}"
 
+    def _build_resource_limit_args(self, spec: BoxSpec) -> list[str]:
+        args: list[str] = []
+        if self.cpu_limit_enabled:
+            args.extend(["--cpus", str(spec.cpus)])
+        args.extend(["--memory", f"{spec.memory_mb}m"])
+        args.extend(["--pids-limit", str(spec.pids_limit)])
+        return args
+
     def _build_exec_command(self, workdir: str, cmd: str) -> str:
         quoted_workdir = shlex.quote(workdir)
         return f"mkdir -p {quoted_workdir} && cd {quoted_workdir} && {cmd}"
@@ -430,3 +440,16 @@ class CLISandboxBackend(BaseSandboxBackend):
 class DockerBackend(CLISandboxBackend):
     def __init__(self, logger: logging.Logger):
         super().__init__(logger=logger, command="docker", backend_name="docker")
+
+    def configure(self, config: dict) -> None:
+        raw_value = config.get("cpu_limit_enabled", True)
+        if isinstance(raw_value, bool):
+            enabled = raw_value
+        else:
+            enabled = str(raw_value).strip().lower() not in _FALSE_VALUES
+        self.cpu_limit_enabled = enabled
+        if not enabled:
+            self.logger.warning(
+                "Docker sandbox CPU limit is disabled by config "
+                "(box.docker.cpu_limit_enabled=false); containers will be started without --cpus."
+            )