langbot-plugin 0.3.10__tar.gz → 0.4.0__tar.gz

langbot_plugin-0.4.0/.github/workflows/test.yml

@@ -0,0 +1,46 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+      - test-build
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  unit-tests:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+      - name: Run tests with coverage
+        run: |
+          uv run --python ${{ matrix.python-version }} pytest \
+            --cov=langbot_plugin \
+            --cov-report=term-missing \
+            --cov-fail-under=75
+
+  test-lint:
+    name: Test Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Ruff tests
+        run: uv run ruff check tests --output-format=concise

{langbot_plugin-0.3.10 → langbot_plugin-0.4.0}/.gitignore

@@ -174,6 +174,7 @@ cython_debug/
 .pypirc
 
 /data/plugins/
+/data/box/
 /debug/
 uv.lock
 src/.DS_Store

{langbot_plugin-0.3.10 → langbot_plugin-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langbot-plugin
-Version: 0.3.10
+Version: 0.4.0
 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
@@ -9,7 +9,9 @@ Author-email: Junyan Qin <rockchinq@gmail.com>
 License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: aiohttp>=3.9.0
 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: pip>=25.2

{langbot_plugin-0.3.10 → langbot_plugin-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langbot-plugin"
-version = "0.3.10"
+version = "0.4.0"
 description = "This package contains the SDK, CLI for building plugins for LangBot, plus the runtime for hosting LangBot plugins"
 readme = "README.md"
 authors = [
@@ -9,7 +9,9 @@ authors = [
 requires-python = ">=3.10"
 dependencies = [
     "aiofiles>=24.1.0",
+    "aiohttp>=3.9.0",
     "dotenv>=0.9.9",
+    "e2b>=2.15",
     "httpx>=0.28.1",
     "jinja2>=3.1.6",
     "pip>=25.2",
@@ -27,6 +29,8 @@ dependencies = [
 [dependency-groups]
 dev = [
     "mypy>=1.16.0",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
     "ruff>=0.11.12",
 ]
 
@@ -44,3 +48,17 @@ Issues = "https://github.com/langbot-app/langbot-plugin-sdk/issues"
 
 [tool.setuptools]
 package-data = { "langbot_plugin" = ["assets/templates/*", "assets/*.js"] }
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+asyncio_mode = "auto"
+pythonpath = ["."]
+
+[tool.coverage.run]
+branch = true
+source = ["langbot_plugin"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true

{langbot_plugin-0.3.10 → langbot_plugin-0.4.0}/src/langbot_plugin/api/entities/builtin/command/context.py

@@ -37,8 +37,8 @@ class CommandReturn(pydantic.BaseModel):
     """错误，保留供系统使用，插件逻辑报错请自行使用 text 传递
     """
 
-    @classmethod
     @pydantic.field_validator("error", mode="before")
+    @classmethod
     def _validate_error(
         cls, v: Optional[errors.CommandError]
     ) -> Optional[errors.CommandError]:
@@ -46,9 +46,8 @@ class CommandReturn(pydantic.BaseModel):
             return errors.CommandError(message=v.message)
         return v
 
-    @classmethod
     @pydantic.field_serializer("error")
-    def _serialize_error(cls, v: Optional[errors.CommandError]) -> Optional[str]:
+    def _serialize_error(self, v: Optional[errors.CommandError]) -> Optional[str]:
         if v is not None:
             return v.message
         return v

{langbot_plugin-0.3.10 → langbot_plugin-0.4.0}/src/langbot_plugin/api/entities/builtin/command/errors.py

@@ -13,20 +13,20 @@ class CommandError(pydantic.BaseModel):
 
 
 class CommandNotFoundError(CommandError):
-    def __init__(self, message: str = None):
+    def __init__(self, message: str = ""):
         super().__init__("未知命令: " + message)
 
 
 class CommandPrivilegeError(CommandError):
-    def __init__(self, message: str = None):
+    def __init__(self, message: str = ""):
         super().__init__("权限不足: " + message)
 
 
 class ParamNotEnoughError(CommandError):
-    def __init__(self, message: str = None):
+    def __init__(self, message: str = ""):
         super().__init__("参数不足: " + message)
 
 
 class CommandOperationError(CommandError):
-    def __init__(self, message: str = None):
+    def __init__(self, message: str = ""):
         super().__init__("操作失败: " + message)

{langbot_plugin-0.3.10 → langbot_plugin-0.4.0}/src/langbot_plugin/api/entities/builtin/provider/message.py

@@ -132,7 +132,8 @@ class Message(pydantic.BaseModel):
                             platform_message.File(url=ce.file_url, name=ce.file_name)
                         )
                 elif ce.type == "image_url":
-                    assert ce.image_url is not None
+                    if ce.image_url is None:
+                        raise ValueError("image_url content requires image_url payload")
                     if ce.image_url.url.startswith("http"):
                         mc.append(platform_message.Image(url=ce.image_url.url))
                     # else:  # base64, for backward compatibility
@@ -223,6 +224,8 @@ class MessageChunk(pydantic.BaseModel):
                             platform_message.File(url=ce.file_url, name=ce.file_name)
                         )
                 elif ce.type == "image_url":
+                    if ce.image_url is None:
+                        raise ValueError("image_url content requires image_url payload")
                     if ce.image_url.url.startswith("http"):
                         mc.append(platform_message.Image(url=ce.image_url.url))
                     # else:  # base64

langbot_plugin-0.4.0/src/langbot_plugin/box/__init__.py

@@ -0,0 +1,5 @@
+"""LangBot Box runtime package."""
+
+from .client import BoxRuntimeClient, ActionRPCBoxClient
+
+__all__ = ['BoxRuntimeClient', 'ActionRPCBoxClient']

langbot_plugin-0.4.0/src/langbot_plugin/box/actions.py

@@ -0,0 +1,34 @@
+"""Box-specific action types for the action RPC protocol."""
+
+from __future__ import annotations
+
+from langbot_plugin.entities.io.actions.enums import ActionType
+
+
+class LangBotToBoxAction(ActionType):
+    """Actions sent from LangBot to the Box runtime."""
+
+    INIT = "box_init"  # Initialize with full box config (highest priority)
+    HEALTH = "box_health"
+    STATUS = "box_status"
+    EXEC = "box_exec"
+    CREATE_SESSION = "box_create_session"
+    GET_SESSION = "box_get_session"
+    GET_SESSIONS = "box_get_sessions"
+    DELETE_SESSION = "box_delete_session"
+    START_MANAGED_PROCESS = "box_start_managed_process"
+    GET_MANAGED_PROCESS = "box_get_managed_process"
+    STOP_MANAGED_PROCESS = "box_stop_managed_process"
+    GET_BACKEND_INFO = "box_get_backend_info"
+    LIST_SKILLS = "box_list_skills"
+    GET_SKILL = "box_get_skill"
+    CREATE_SKILL = "box_create_skill"
+    UPDATE_SKILL = "box_update_skill"
+    DELETE_SKILL = "box_delete_skill"
+    SCAN_SKILL_DIRECTORY = "box_scan_skill_directory"
+    LIST_SKILL_FILES = "box_list_skill_files"
+    READ_SKILL_FILE = "box_read_skill_file"
+    WRITE_SKILL_FILE = "box_write_skill_file"
+    PREVIEW_SKILL_ZIP = "box_preview_skill_zip"
+    INSTALL_SKILL_ZIP = "box_install_skill_zip"
+    SHUTDOWN = "box_shutdown"

langbot_plugin-0.4.0/src/langbot_plugin/box/backend.py

@@ -0,0 +1,411 @@
+from __future__ import annotations
+
+import abc
+import asyncio
+import dataclasses
+import datetime as dt
+import logging
+import re
+import shlex
+import shutil
+import uuid
+
+from .errors import BoxError
+from .models import (
+    BoxExecutionResult,
+    BoxExecutionStatus,
+    BoxHostMountMode,
+    BoxNetworkMode,
+    BoxSessionInfo,
+    BoxSpec,
+)
+from .security import validate_sandbox_security
+
+# Hard cap on raw subprocess output to prevent unbounded memory usage.
+# Container timeout already bounds duration, but fast commands can still
+# 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
+
+
+@dataclasses.dataclass(slots=True)
+class _CommandResult:
+    return_code: int
+    stdout: str
+    stderr: str
+    timed_out: bool = False
+
+
+class BaseSandboxBackend(abc.ABC):
+    name: str
+    instance_id: str = ''
+
+    def __init__(self, logger: logging.Logger):
+        self.logger = logger
+
+    async def initialize(self):
+        return None
+
+    @abc.abstractmethod
+    async def is_available(self) -> bool:
+        pass
+
+    @abc.abstractmethod
+    async def start_session(self, spec: BoxSpec) -> BoxSessionInfo:
+        pass
+
+    @abc.abstractmethod
+    async def exec(self, session: BoxSessionInfo, spec: BoxSpec) -> BoxExecutionResult:
+        pass
+
+    @abc.abstractmethod
+    async def stop_session(self, session: BoxSessionInfo):
+        pass
+
+    async def is_session_alive(self, session: BoxSessionInfo) -> bool:
+        return True
+
+    async def start_managed_process(self, session: BoxSessionInfo, spec):
+        raise BoxError(f'{self.name} backend does not support managed processes')
+
+    async def cleanup_orphaned_containers(self, current_instance_id: str = ''):
+        """Remove lingering containers from previous runs. No-op by default."""
+        pass
+
+
+class CLISandboxBackend(BaseSandboxBackend):
+    command: str
+
+    def __init__(self, logger: logging.Logger, command: str, backend_name: str):
+        super().__init__(logger)
+        self.command = command
+        self.name = backend_name
+
+    async def is_available(self) -> bool:
+        if shutil.which(self.command) is None:
+            return False
+
+        result = await self._run_command([self.command, 'info'], timeout_sec=5, check=False)
+        return result.return_code == 0 and not result.timed_out
+
+    async def start_session(self, spec: BoxSpec) -> BoxSessionInfo:
+        validate_sandbox_security(spec)
+
+        now = dt.datetime.now(dt.timezone.utc)
+        container_name = self._build_container_name(spec.session_id)
+
+        args = [
+            self.command,
+            'run',
+            '-d',
+        ]
+
+        if not spec.persistent:
+            args.append('--rm')
+
+        args.extend([
+            '--name',
+            container_name,
+            '--label',
+            'langbot.box=true',
+            '--label',
+            f'langbot.session_id={spec.session_id}',
+            '--label',
+            f'langbot.box.instance_id={self.instance_id}',
+        ])
+
+        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)])
+
+        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:
+            mount_spec = f'{spec.host_path}:{spec.mount_path}:{spec.host_path_mode.value}'
+            args.extend(['-v', mount_spec])
+
+        for mount in spec.extra_mounts:
+            if mount.mode != BoxHostMountMode.NONE:
+                args.extend(['-v', f'{mount.host_path}:{mount.mount_path}:{mount.mode.value}'])
+
+        args.extend([spec.image, 'sh', '-lc', 'while true; do sleep 3600; done'])
+
+        self.logger.info(
+            f'LangBot Box backend start_session: backend={self.name} '
+            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'read_only_rootfs={spec.read_only_rootfs} workspace_quota_mb={spec.workspace_quota_mb}'
+        )
+
+        await self._run_command(args, timeout_sec=30, check=True)
+
+        return BoxSessionInfo(
+            session_id=spec.session_id,
+            backend_name=self.name,
+            backend_session_id=container_name,
+            image=spec.image,
+            network=spec.network,
+            host_path=spec.host_path,
+            host_path_mode=spec.host_path_mode,
+            mount_path=spec.mount_path,
+            persistent=spec.persistent,
+            cpus=spec.cpus,
+            memory_mb=spec.memory_mb,
+            pids_limit=spec.pids_limit,
+            read_only_rootfs=spec.read_only_rootfs,
+            workspace_quota_mb=spec.workspace_quota_mb,
+            created_at=now,
+            last_used_at=now,
+        )
+
+    async def exec(self, session: BoxSessionInfo, spec: BoxSpec) -> BoxExecutionResult:
+        start = dt.datetime.now(dt.timezone.utc)
+        args = [self.command, 'exec']
+
+        for key, value in spec.env.items():
+            args.extend(['-e', f'{key}={value}'])
+
+        args.extend(
+            [
+                session.backend_session_id,
+                'sh',
+                '-lc',
+                self._build_exec_command(spec.workdir, spec.cmd),
+            ]
+        )
+
+        cmd_preview = spec.cmd.strip()
+        if len(cmd_preview) > 400:
+            cmd_preview = f'{cmd_preview[:397]}...'
+        self.logger.info(
+            f'LangBot Box backend exec: backend={self.name} '
+            f'session_id={session.session_id} container_name={session.backend_session_id} '
+            f'workdir={spec.workdir} timeout_sec={spec.timeout_sec} '
+            f'env_keys={sorted(spec.env.keys())} cmd={cmd_preview}'
+        )
+
+        result = await self._run_command(args, timeout_sec=spec.timeout_sec, check=False)
+        duration_ms = int((dt.datetime.now(dt.timezone.utc) - start).total_seconds() * 1000)
+
+        if result.timed_out:
+            return BoxExecutionResult(
+                session_id=session.session_id,
+                backend_name=self.name,
+                status=BoxExecutionStatus.TIMED_OUT,
+                exit_code=None,
+                stdout=result.stdout,
+                stderr=result.stderr or f'Command timed out after {spec.timeout_sec} seconds.',
+                duration_ms=duration_ms,
+            )
+
+        return BoxExecutionResult(
+            session_id=session.session_id,
+            backend_name=self.name,
+            status=BoxExecutionStatus.COMPLETED,
+            exit_code=result.return_code,
+            stdout=result.stdout,
+            stderr=result.stderr,
+            duration_ms=duration_ms,
+        )
+
+    async def stop_session(self, session: BoxSessionInfo):
+        self.logger.info(
+            f'LangBot Box backend stop_session: backend={self.name} '
+            f'session_id={session.session_id} container_name={session.backend_session_id}'
+        )
+        await self._run_command(
+            [self.command, 'rm', '-f', session.backend_session_id],
+            timeout_sec=20,
+            check=False,
+        )
+
+    async def is_session_alive(self, session: BoxSessionInfo) -> bool:
+        result = await self._run_command(
+            [
+                self.command,
+                'inspect',
+                '-f',
+                '{{.State.Running}}',
+                session.backend_session_id,
+            ],
+            timeout_sec=5,
+            check=False,
+        )
+        return result.return_code == 0 and result.stdout.strip().lower() == 'true'
+
+    async def cleanup_orphaned_containers(self, current_instance_id: str = ''):
+        """Remove langbot.box containers from previous instances.
+
+        Only removes containers whose ``langbot.box.instance_id`` label does
+        NOT match *current_instance_id*.  Containers without the label (from
+        older versions) are also removed.
+        """
+        result = await self._run_command(
+            [
+                self.command,
+                'ps',
+                '-a',
+                '--filter',
+                'label=langbot.box=true',
+                '--format',
+                '{{.ID}}\t{{.Label "langbot.box.instance_id"}}',
+            ],
+            timeout_sec=10,
+            check=False,
+        )
+        if result.return_code != 0 or not result.stdout.strip():
+            return
+        orphan_ids = []
+        for line in result.stdout.strip().split('\n'):
+            line = line.strip()
+            if not line:
+                continue
+            parts = line.split('\t', 1)
+            cid = parts[0].strip()
+            label_instance = parts[1].strip() if len(parts) > 1 else ''
+            if label_instance != current_instance_id:
+                orphan_ids.append(cid)
+        if not orphan_ids:
+            return
+        for cid in orphan_ids:
+            self.logger.info(f'Cleaning up orphaned Box container: {cid}')
+        await self._run_command(
+            [self.command, 'rm', '-f', *orphan_ids],
+            timeout_sec=30,
+            check=False,
+        )
+
+    async def start_managed_process(self, session: BoxSessionInfo, spec) -> asyncio.subprocess.Process:
+        args = [self.command, 'exec', '-i']
+
+        for key, value in spec.env.items():
+            args.extend(['-e', f'{key}={value}'])
+
+        args.extend(
+            [
+                session.backend_session_id,
+                'sh',
+                '-lc',
+                self._build_spawn_command(spec.cwd, spec.command, spec.args),
+            ]
+        )
+
+        self.logger.info(
+            f'LangBot Box backend start_managed_process: backend={self.name} '
+            f'session_id={session.session_id} container_name={session.backend_session_id} '
+            f'cwd={spec.cwd} env_keys={sorted(spec.env.keys())} command={spec.command} args={spec.args}'
+        )
+
+        return await asyncio.create_subprocess_exec(
+            *args,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+    def _build_container_name(self, session_id: str) -> str:
+        normalized = re.sub(r'[^a-zA-Z0-9_.-]+', '-', session_id).strip('-').lower() or 'session'
+        suffix = uuid.uuid4().hex[:8]
+        return f'langbot-box-{normalized[:32]}-{suffix}'
+
+    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}'
+
+    def _build_spawn_command(self, cwd: str, command: str, args: list[str]) -> str:
+        quoted_cwd = shlex.quote(cwd)
+        command_parts = [shlex.quote(command), *[shlex.quote(arg) for arg in args]]
+        return f'mkdir -p {quoted_cwd} && cd {quoted_cwd} && exec {" ".join(command_parts)}'
+
+    async def _run_command(
+        self,
+        args: list[str],
+        timeout_sec: int,
+        check: bool,
+    ) -> _CommandResult:
+        process = await asyncio.create_subprocess_exec(
+            *args,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout_task = asyncio.create_task(self._read_stream(process.stdout))
+        stderr_task = asyncio.create_task(self._read_stream(process.stderr))
+
+        timed_out = False
+        try:
+            await asyncio.wait_for(process.wait(), timeout=timeout_sec)
+        except asyncio.TimeoutError:
+            process.kill()
+            timed_out = True
+            await process.wait()
+
+        stdout_bytes, stdout_total = await stdout_task
+        stderr_bytes, stderr_total = await stderr_task
+
+        if timed_out:
+            return _CommandResult(
+                return_code=-1,
+                stdout=self._clip_captured_bytes(stdout_bytes, stdout_total),
+                stderr=self._clip_captured_bytes(stderr_bytes, stderr_total),
+                timed_out=True,
+            )
+
+        stdout = self._clip_captured_bytes(stdout_bytes, stdout_total)
+        stderr = self._clip_captured_bytes(stderr_bytes, stderr_total)
+
+        if check and process.returncode != 0:
+            raise BoxError(self._format_cli_error(stderr or stdout or 'unknown backend error'))
+
+        return _CommandResult(
+            return_code=process.returncode,
+            stdout=stdout,
+            stderr=stderr,
+            timed_out=False,
+        )
+
+    @staticmethod
+    def _clip_captured_bytes(data: bytes, total_size: int, limit: int = _MAX_RAW_OUTPUT_BYTES) -> str:
+        text = data.decode('utf-8', errors='replace').strip()
+        if total_size > limit:
+            text += f'\n... [raw output clipped at {limit} bytes, {total_size - limit} bytes discarded]'
+        return text
+
+    @staticmethod
+    async def _read_stream(
+        stream: asyncio.StreamReader | None,
+        limit: int = _MAX_RAW_OUTPUT_BYTES,
+    ) -> tuple[bytes, int]:
+        if stream is None:
+            return b'', 0
+
+        chunks = bytearray()
+        total_size = 0
+        while True:
+            chunk = await stream.read(65536)
+            if not chunk:
+                break
+            total_size += len(chunk)
+            remaining = limit - len(chunks)
+            if remaining > 0:
+                chunks.extend(chunk[:remaining])
+
+        return bytes(chunks), total_size
+
+    def _format_cli_error(self, message: str) -> str:
+        message = ' '.join(message.split())
+        if len(message) > 300:
+            message = f'{message[:297]}...'
+        return f'{self.name} backend error: {message}'
+
+
+class DockerBackend(CLISandboxBackend):
+    def __init__(self, logger: logging.Logger):
+        super().__init__(logger=logger, command='docker', backend_name='docker')