langbot-plugin 0.7.12__tar.gz → 0.7.13__tar.gz

{langbot_plugin-0.7.12 → langbot_plugin-0.7.13}/ARCHITECTURE.md

@@ -20,7 +20,7 @@ The runtime code under `src/langbot_plugin/runtime/` is AGPL; the rest of the re
 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.
+- This SDK repo owns plugin author APIs, shared message/event/context entities, the action RPC protocol, the execution-independent filesystem Skill store, `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.
@@ -37,6 +37,8 @@ langbot-plugin-sdk/
 │   ├── cli/                  # `lbp` entrypoint and subcommands
 │   ├── runtime/              # Plugin Runtime (`lbp rt`)
 │   ├── box/                  # Box Runtime (`lbp box`)
+│   ├── skill_store.py        # Execution-independent Skill package storage
+│   ├── workspace.py          # Neutral Workspace namespace identity
 │   ├── entities/io/          # Action RPC request/response/error/action models
 │   ├── assets/               # Scaffolding templates and page SDK asset
 │   └── utils/
@@ -420,7 +422,7 @@ 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/models.py`: generic `BoxSpec`/read-only mount contracts, 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.
@@ -428,7 +430,7 @@ Important modules:
   trusted local development.
 - `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.
+- `skill_store.py`: generic Skill package CRUD, revision, and read-only resource helpers; it does not start or connect to Box.
 - `box/security.py`: path/security helper logic.
 
 Default Box WebSocket endpoints on port `5410`:
@@ -437,8 +439,34 @@ Default Box WebSocket endpoints on port `5410`:
 - `/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.
 
-Box keeps durable skill/storage paths in an `(instance, workspace)` namespace,
-while sandbox sessions and managed processes use an
+The Skill store keeps an authoritative registry in an `(instance, workspace)`
+namespace. Each successful publication validates a complete staging tree,
+computes one `sha256-tree-v1` digest, atomically installs an immutable revision,
+and only then advances the registry pointer. Updates require the current
+`base_revision`; deletion removes the pointer while retaining revisions for
+active or recoverable runs. Former mutable package directories are only a
+one-time online-upgrade import source.
+
+LangBot Core composes pinned revisions into generic read-only `BoxMountSpec`
+values. Ordinary fixed mounts include `content_digest` and `manifest_path` in
+the session signature; supported digest-addressed packages are excluded from it.
+Digest-addressed packages use the reserved
+`/opt/langbot-artifacts/<digest>` namespace. Docker/Podman pre-mount a read-only
+cache and atomically populate verified revisions before execution. E2B seals and
+verifies packages before publishing stable digest projections. These packages can
+be added after a Box is acquired, without replacing the session. nsjail applies
+all mounts independently per execution. Fixed ordinary host mounts still reject
+incompatible reuse; a conflict never implicitly destroys the existing session.
+The unsafe host development backend maps each execution's paths without claiming
+filesystem isolation. Cached artifacts are shared within a Box, just like its
+Workspace; version pinning is not isolation between commands sharing that Box. Box
+has no Skill model, CRUD API, or `SKILL.md` knowledge in its normal path; it only
+validates and mounts artifacts. Copy-based backends prepare a digest-specific
+staging tree, verify the complete manifest, and publish it before projecting the
+mount path, so partial transfers and removed-file residue cannot be executed.
+Core and the Box Runtime SDK are upgraded in lockstep; Box deliberately rejects
+retired Skill-aware payload fields instead of carrying a mixed-version bridge.
+Sandbox sessions and managed processes use an
 `(instance, workspace, placement_generation)` namespace. Authenticated tenant
 RPCs advance a monotonic generation fence, cancel in-flight older RPCs, and
 retire older sessions. Managed-process relay handshakes carry Workspace and
@@ -484,5 +512,6 @@ The SDK `AGENTS.md` keeps the short command checklist; this file keeps the struc
 - 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.
+- Keep Box limited to generic sandbox/session/mount semantics; Skill policy and
+  package orchestration belong to LangBot Core.
 - Prefer tests around protocol shape and black-box CLI behavior when changing runtime boundaries.

{langbot_plugin-0.7.12 → langbot_plugin-0.7.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: langbot-plugin
-Version: 0.7.12
+Version: 0.7.13
 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.7.12 → langbot_plugin-0.7.13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langbot-plugin"
-version = "0.7.12"
+version = "0.7.13"
 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.7.13/src/langbot_plugin/artifact.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import posixpath
+import stat
+from collections.abc import Collection
+
+
+TREE_MANIFEST_ALGORITHM = "sha256-tree-v1"
+_MAX_MANIFEST_BYTES = 4 * 1024 * 1024
+
+
+def validate_tree_manifest(
+    manifest: dict,
+    *,
+    max_files: int,
+    max_total_bytes: int,
+    subject: str = "Artifact",
+) -> tuple[str, dict]:
+    """Validate a persisted manifest and return its canonical digest."""
+
+    if not isinstance(manifest, dict) or set(manifest) != {
+        "algorithm",
+        "files",
+        "total_bytes",
+    }:
+        raise ValueError(f"{subject} manifest has an invalid shape")
+    if manifest["algorithm"] != TREE_MANIFEST_ALGORITHM:
+        raise ValueError(f"{subject} manifest uses an unsupported algorithm")
+    files = manifest["files"]
+    if not isinstance(files, list) or len(files) > max_files:
+        raise ValueError(f"{subject} manifest contains too many files")
+    seen: set[str] = set()
+    calculated_total = 0
+    for entry in files:
+        if not isinstance(entry, dict) or set(entry) != {
+            "path",
+            "size",
+            "sha256",
+            "executable",
+        }:
+            raise ValueError(f"{subject} manifest contains an invalid file entry")
+        path = entry["path"]
+        if (
+            not isinstance(path, str)
+            or not path
+            or "\0" in path
+            or "\\" in path
+            or posixpath.isabs(path)
+            or posixpath.normpath(path) != path
+            or path in {".", ".."}
+            or path.startswith("../")
+            or path in seen
+        ):
+            raise ValueError(f"{subject} manifest contains an unsafe path")
+        seen.add(path)
+        size = entry["size"]
+        if isinstance(size, bool) or not isinstance(size, int) or size < 0:
+            raise ValueError(f"{subject} manifest contains an invalid file size")
+        calculated_total += size
+        digest = entry["sha256"]
+        if (
+            not isinstance(digest, str)
+            or len(digest) != 64
+            or any(ch not in "0123456789abcdef" for ch in digest)
+        ):
+            raise ValueError(f"{subject} manifest contains an invalid file digest")
+        if not isinstance(entry["executable"], bool):
+            raise ValueError(f"{subject} manifest contains an invalid file mode")
+
+    declared_total = manifest["total_bytes"]
+    if (
+        isinstance(declared_total, bool)
+        or not isinstance(declared_total, int)
+        or declared_total != calculated_total
+        or declared_total > max_total_bytes
+    ):
+        raise ValueError(f"{subject} manifest contains an invalid total size")
+    canonical = json.dumps(
+        manifest,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("utf-8")
+    return f"sha256:{hashlib.sha256(canonical).hexdigest()}", manifest
+
+
+def load_tree_manifest(
+    path: str,
+    *,
+    max_files: int,
+    max_total_bytes: int,
+    subject: str = "Artifact",
+) -> tuple[str, dict]:
+    if os.path.getsize(path) > _MAX_MANIFEST_BYTES:
+        raise ValueError(f"{subject} manifest is too large")
+    with open(path, "rb") as file:
+        body = file.read(_MAX_MANIFEST_BYTES + 1)
+    if len(body) > _MAX_MANIFEST_BYTES:
+        raise ValueError(f"{subject} manifest is too large")
+    try:
+        manifest = json.loads(body)
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ValueError(f"{subject} manifest is invalid JSON") from exc
+    return validate_tree_manifest(
+        manifest,
+        max_files=max_files,
+        max_total_bytes=max_total_bytes,
+        subject=subject,
+    )
+
+
+def build_tree_manifest(
+    root: str,
+    *,
+    max_files: int,
+    max_total_bytes: int,
+    skip_directories: Collection[str] = (),
+    subject: str = "Artifact",
+) -> tuple[str, dict]:
+    """Validate a regular-file tree and return its canonical content digest."""
+
+    resolved_root = os.path.realpath(str(root or "").strip())
+    if not resolved_root or not os.path.isdir(resolved_root):
+        raise ValueError(f"{subject} directory is unavailable")
+
+    files: list[dict] = []
+    total_bytes = 0
+    for current_root, dir_names, file_names in os.walk(
+        resolved_root,
+        followlinks=False,
+    ):
+        dir_names[:] = [name for name in dir_names if name not in skip_directories]
+        dir_names.sort()
+        file_names.sort()
+        for directory_name in dir_names:
+            if os.path.islink(os.path.join(current_root, directory_name)):
+                raise ValueError(f"{subject} cannot contain symbolic links")
+        for file_name in file_names:
+            path = os.path.join(current_root, file_name)
+            file_stat = os.stat(path, follow_symlinks=False)
+            if os.path.islink(path):
+                raise ValueError(f"{subject} cannot contain symbolic links")
+            if not stat.S_ISREG(file_stat.st_mode):
+                raise ValueError(f"{subject} can contain regular files only")
+            if len(files) >= max_files:
+                raise ValueError(f"{subject} contains too many files")
+            total_bytes += file_stat.st_size
+            if total_bytes > max_total_bytes:
+                raise ValueError(f"{subject} is too large")
+
+            file_digest = hashlib.sha256()
+            with open(path, "rb") as file:
+                while True:
+                    chunk = file.read(256 * 1024)
+                    if not chunk:
+                        break
+                    file_digest.update(chunk)
+            files.append(
+                {
+                    "path": os.path.relpath(path, resolved_root).replace(os.sep, "/"),
+                    "size": file_stat.st_size,
+                    "sha256": file_digest.hexdigest(),
+                    "executable": bool(stat.S_IMODE(file_stat.st_mode) & 0o111),
+                }
+            )
+
+    manifest = {
+        "algorithm": TREE_MANIFEST_ALGORITHM,
+        "files": files,
+        "total_bytes": total_bytes,
+    }
+    return validate_tree_manifest(
+        manifest,
+        max_files=max_files,
+        max_total_bytes=max_total_bytes,
+        subject=subject,
+    )
+
+
+__all__ = [
+    "TREE_MANIFEST_ALGORITHM",
+    "build_tree_manifest",
+    "load_tree_manifest",
+    "validate_tree_manifest",
+]
+
+
+def materialize_tree(
+    source: str, manifest_path: str, expected_digest: str, cache_root: str
+) -> str:
+    """Publish a complete verified tree outside the sandbox before making it visible."""
+    import shutil
+    import tempfile
+
+    max_bytes = 256 * 1024 * 1024
+    digest, manifest = load_tree_manifest(
+        manifest_path, max_files=2048, max_total_bytes=max_bytes
+    )
+    if digest != expected_digest:
+        raise ValueError("Artifact manifest does not match content_digest")
+    target = os.path.join(cache_root, digest[7:])
+    if os.path.isdir(target) and not os.path.islink(target):
+        return target
+    used = sum(
+        os.path.getsize(os.path.join(root, name))
+        for root, _, names in os.walk(cache_root)
+        for name in names
+    )
+    if len(os.listdir(cache_root)) >= 256 or used + manifest["total_bytes"] > max_bytes:
+        raise ValueError("Immutable artifact cache limit reached; acquire a new Box")
+    staging = tempfile.mkdtemp(
+        prefix="langbot-artifact-stage-", dir=os.path.dirname(cache_root)
+    )
+    try:
+        for entry in manifest["files"]:
+            source_path = os.path.join(source, *entry["path"].split("/"))
+            descriptor = os.open(
+                source_path,
+                os.O_RDONLY
+                | getattr(os, "O_NOFOLLOW", 0)
+                | getattr(os, "O_NONBLOCK", 0),
+            )
+            with os.fdopen(descriptor, "rb") as stream:
+                if not stat.S_ISREG(os.fstat(stream.fileno()).st_mode):
+                    raise ValueError("Artifact source must be a regular file")
+                body = stream.read(entry["size"] + 1)
+            if (
+                len(body) != entry["size"]
+                or hashlib.sha256(body).hexdigest() != entry["sha256"]
+            ):
+                raise ValueError(f"Artifact source changed: {entry['path']}")
+            destination = os.path.join(staging, *entry["path"].split("/"))
+            os.makedirs(os.path.dirname(destination), exist_ok=True)
+            with open(destination, "xb") as stream:
+                stream.write(body)
+            os.chmod(destination, 0o555 if entry["executable"] else 0o444)
+        os.chmod(staging, 0o755)
+        os.rename(staging, target)
+        return target
+    finally:
+        if os.path.isdir(staging):
+            shutil.rmtree(staging)

{langbot_plugin-0.7.12 → langbot_plugin-0.7.13}/src/langbot_plugin/box/actions.py

@@ -24,15 +24,4 @@ class LangBotToBoxAction(ActionType):
     STOP_MANAGED_PROCESS = "box_stop_managed_process"
     GET_BACKEND_INFO = "box_get_backend_info"
     GET_STORAGE_ANALYSIS = "box_get_storage_analysis"
-    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.7.12 → langbot_plugin-0.7.13}/src/langbot_plugin/box/backend.py

@@ -10,9 +10,14 @@ import re
 import shlex
 import shutil
 import uuid
+import tempfile
+
+from ..artifact import materialize_tree
+from ..runtime import bounded_executor
 
 from .errors import BoxError
 from .models import (
+    ARTIFACT_MOUNT_ROOT,
     BoxExecutionResult,
     BoxExecutionStatus,
     BoxHostMountMode,
@@ -41,6 +46,8 @@ class _CommandResult:
 class BaseSandboxBackend(abc.ABC):
     name: str
     instance_id: str = ""
+    execution_scoped_mounts: bool = False
+    content_addressed_mounts: bool = False
 
     def __init__(self, logger: logging.Logger):
         self.logger = logger
@@ -87,7 +94,7 @@ class BaseSandboxBackend(abc.ABC):
             "mount_isolation": False if strict else None,
             "network_isolation": False if strict else None,
             "hard_workspace_quota": False if strict else None,
-            "hard_skill_storage_quota": False if strict else None,
+            "hard_read_only_mount_quota": False if strict else None,
             "bounded_ephemeral_storage": False if strict else None,
             "inode_quota": False if strict else None,
         }
@@ -154,6 +161,7 @@ class BaseSandboxBackend(abc.ABC):
 
 
 class CLISandboxBackend(BaseSandboxBackend):
+    content_addressed_mounts = True
     command: str
 
     def __init__(self, logger: logging.Logger, command: str, backend_name: str):
@@ -161,6 +169,7 @@ class CLISandboxBackend(BaseSandboxBackend):
         self.command = command
         self.name = backend_name
         self.cpu_limit_enabled = True
+        self._artifact_roots: dict[str, str] = {}
 
     async def is_available(self) -> bool:
         if shutil.which(self.command) is None:
@@ -215,8 +224,12 @@ class CLISandboxBackend(BaseSandboxBackend):
             )
             args.extend(["-v", mount_spec])
 
+        artifact_root = tempfile.mkdtemp(prefix="langbot-box-artifacts-")
+        os.chmod(artifact_root, 0o755)
+        self._artifact_roots[container_name] = artifact_root
+        args.extend(["-v", f"{artifact_root}:{ARTIFACT_MOUNT_ROOT}:ro"])
         for mount in spec.extra_mounts:
-            if mount.mode != BoxHostMountMode.NONE:
+            if mount.mode != BoxHostMountMode.NONE and not mount.is_content_addressed:
                 args.extend(
                     ["-v", f"{mount.host_path}:{mount.mount_path}:{mount.mode.value}"]
                 )
@@ -233,7 +246,27 @@ class CLISandboxBackend(BaseSandboxBackend):
             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)
+        start_task = None
+        try:
+            await self._prepare_artifacts(container_name, spec)
+            start_task = asyncio.create_task(
+                self._run_command(args, timeout_sec=30, check=True)
+            )
+            await asyncio.shield(start_task)
+        except BaseException:
+            if start_task is not None:
+                try:
+                    await start_task
+                except BaseException:
+                    pass
+                await self._run_command(
+                    [self.command, "rm", "-f", container_name],
+                    timeout_sec=20,
+                    check=False,
+                )
+            self._artifact_roots.pop(container_name, None)
+            shutil.rmtree(artifact_root)
+            raise
 
         return BoxSessionInfo(
             session_id=spec.session_id,
@@ -254,7 +287,29 @@ class CLISandboxBackend(BaseSandboxBackend):
             last_used_at=now,
         )
 
+    async def _prepare_artifacts(self, session_id: str, spec: BoxSpec) -> None:
+        for mount in spec.extra_mounts:
+            if mount.is_content_addressed:
+                root = self._artifact_roots.get(session_id)
+                if root is None:
+                    raise BoxError(
+                        "Immutable artifact cache is unavailable; acquire a new Box"
+                    )
+                try:
+                    await bounded_executor.run_blocking_atomic(
+                        materialize_tree,
+                        mount.host_path,
+                        mount.manifest_path,
+                        mount.content_digest,
+                        root,
+                    )
+                except (OSError, ValueError) as exc:
+                    raise BoxError(
+                        f"Immutable artifact preparation failed: {exc}"
+                    ) from exc
+
     async def exec(self, session: BoxSessionInfo, spec: BoxSpec) -> BoxExecutionResult:
+        await self._prepare_artifacts(session.backend_session_id, spec)
         start = dt.datetime.now(dt.timezone.utc)
         args = [self.command, "exec"]
 
@@ -316,11 +371,15 @@ class CLISandboxBackend(BaseSandboxBackend):
             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(
+        result = await self._run_command(
             [self.command, "rm", "-f", session.backend_session_id],
             timeout_sec=20,
             check=False,
         )
+        if result.return_code == 0:
+            root = self._artifact_roots.pop(session.backend_session_id, None)
+            if root is not None:
+                await bounded_executor.run_blocking_cleanup(shutil.rmtree, root)
 
     async def is_session_alive(self, session: BoxSessionInfo) -> bool:
         result = await self._run_command(