langbot-plugin 0.6.1b2__tar.gz → 0.6.3__tar.gz

{langbot_plugin-0.6.1b2 → langbot_plugin-0.6.3}/ARCHITECTURE.md

@@ -161,13 +161,27 @@ actions reject tenant context. Plugin payload fields are never authoritative
 for these bindings.
 
 In the `shared` profile, `PluginManager` indexes desired state by the complete
-installation binding. The instance-scoped `RECONCILE_PLUGIN_INSTALLATIONS`
+installation binding. Each desired-state entry has an additive
+`execution_mode`: omission or `dedicated` preserves the historical one-process
+per installation behavior, while `shared-runtime-v1` opts a certified
+`shared-runtime-v1` installation into a digest-scoped worker pool. Core is
+responsible for selecting `shared-runtime-v1` only after certification succeeds;
+the Runtime never infers shared authority from tenant-controlled manifest data.
+The instance-scoped `RECONCILE_PLUGIN_INSTALLATIONS`
 action replays the authoritative set, while tenant-scoped
 `APPLY_PLUGIN_INSTALLATION` and `REMOVE_PLUGIN_INSTALLATION` actions change one
 installation. Newer placement generations or Runtime revisions fence the old
 worker immediately; stale or cross-Workspace transitions fail closed.
 
-Each enabled installation is owned by an installation-scoped Supervisor.
+Dedicated enabled installations remain owned by installation-scoped
+Supervisors. A certified shared worker is keyed by the raw artifact digest and
+currently has pool size one: the first slot attach starts it and the last slot
+detach stops it. Installations sharing that process retain separate
+`BasePlugin`, component, config, Host authority, and lifecycle slots. Updating
+one slot reinitializes that slot without restarting siblings. Revision and
+generation fencing remove the exact stale slot, cancel its in-flight actions,
+and prevent background calls after detach.
+
 Unexpected worker exit is recovered with bounded exponential backoff. Disable,
 remove, placement generation changes, Runtime revision changes, and shutdown
 fence the old Supervisor before it can relaunch, while reconcile and control
@@ -183,9 +197,14 @@ installation or Workspace identity.
 
 Plugin packages are verified against `artifact_digest` and extracted once into
 a read-only `artifacts/sha256/<digest>/code` tree. Installations may share that
-code tree, but each gets a separate process and private `home`, `tmp`, and `data`
-directories. A worker receives a short-lived, one-use registration capability
-bound to the complete installation tuple; it cannot select its own tenant scope.
+code tree. Dedicated mode gives each installation a separate process and private
+`home`, `tmp`, and `data` directories. Certified shared workers mount no
+installation or tenant-writable directory; their writable scratch belongs to
+the digest process and tenant state must go through Host actions. A dedicated
+worker capability is bound to one complete installation tuple. A shared worker
+capability is additionally bound to its digest; after registration, every slot
+RPC carries an exact current `InstallationBinding` and cannot select or rebind
+tenant scope.
 
 Before any desired-state artifact worker is launched, the Runtime prepares an
 immutable dependency tree. The resulting `site-packages` tree is keyed by the
@@ -197,7 +216,8 @@ stable `dependency_prepare_failed` desired-state failure. Pip control options in
 an artifact's `requirements.txt` are rejected because only Runtime configuration
 may select indexes or trusted hosts.
 
-Shared workers launch through nsjail with policy-owned cgroup CPU, memory, and
+Workers in the shared Runtime profile launch through nsjail with policy-owned
+cgroup CPU, memory, and
 PID limits plus file/process rlimits. If `require_hard_limits` is true, missing
 nsjail or cgroup v2 delegation makes configuration fail closed. Their dependency
 tree is prepared in a separate nsjail and mounted read-only into the worker.
@@ -230,8 +250,12 @@ Core mechanics:
 - `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/`. Transfer keys are high-entropy opaque basenames; the
-  receiver rejects absolute paths, separators, `..`, and unsafe extensions.
+  under `data/temp/lbp/`. New transfer keys are high-entropy opaque capabilities;
+  the receiver durably binds each capability to its exact authority namespace so
+  a later read can recover that namespace after the action or handler ends. An
+  explicit current context must still match, and the receiver never scans other
+  namespaces. Legacy opaque basenames remain supported. Absolute paths,
+  separators, `..`, and unsafe extensions are rejected.
 
 Action enums are the protocol contract:
 
@@ -305,7 +329,9 @@ An OSS-only exception permits legacy knowledge `FILE_CHUNK` replies carrying
 instance and already-bound Workspace/generation, and its installation capability
 must exactly match a live registered plugin connection. Payload scope is ignored.
 Shared transfers still require a complete binding; candidate artifact pretransfer
-validates that binding without activating desired state.
+validates that binding without activating desired state. Transfer ownership and
+tenant-visible plugin containers/log routing remain installation scoped even
+when several slots use one process.
 
 Legacy OSS plugins are stored under `data/plugins/{author}__{name}`. Runtime
 plugin processes normally run as separate Python processes and connect back via
@@ -324,6 +350,15 @@ APIs (`get_box_status`, `list_boxes`, `acquire_box`) and run-bound operations
 owns atomic capacity enforcement and container reuse/lifecycle. Reusing an existing
 Box is allowed when no additional capacity remains.
 
+Transfer payloads are assembled through private, inode-bound staging files and are
+published with no-overwrite links only after the final chunk succeeds. Durable owner
+records include the published payload device/inode identity, so reads and deletion
+fail closed if a canonical name is replaced. The transfer root assumes no untrusted
+process can mutate its directories with the same Unix UID: such a mutator can rename
+an owned inode to an unknowable name, which cannot be recovered safely. The SDK
+reports that condition as local filesystem corruption, retains owner authority, and
+never treats it as successful cleanup or as cross-tenant access.
+
 A run binds one Box before native sandbox tools or file transfer. The Host does not
 choose a conversation scope or stage attachments before starting the Runner. Input
 references retain the original attachment metadata; import yields paths specific to

{langbot_plugin-0.6.1b2 → langbot_plugin-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: langbot-plugin
-Version: 0.6.1b2
+Version: 0.6.3
 Summary: This package contains the SDK, CLI for building plugins for LangBot, plus the runtime for hosting LangBot plugins
 Project-URL: Homepage, https://langbot.app
 Project-URL: Repository, https://github.com/langbot-app/langbot-plugin-sdk

{langbot_plugin-0.6.1b2 → langbot_plugin-0.6.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langbot-plugin"
-version = "0.6.1b2"
+version = "0.6.3"
 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.6.1b2 → langbot_plugin-0.6.3}/src/langbot_plugin/cli/run/controller.py

@@ -4,6 +4,7 @@ import asyncio
 import os
 import typing
 import logging
+import copy
 
 from langbot_plugin.api.definition.components.manifest import ComponentManifest
 from langbot_plugin.runtime.plugin.container import (
@@ -32,6 +33,7 @@ from langbot_plugin.api.definition.components.page import Page
 from langbot_plugin.api.definition.components.parser.parser import Parser
 from langbot_plugin.api.definition.components.runner.runner import Runner
 from langbot_plugin.entities.io.errors import ConnectionClosedError
+from langbot_plugin.entities.io.context import InstallationBinding
 from langbot_plugin.cli.run.hotreload import HotReloader, reload_plugin_modules
 from langbot_plugin.runtime.security import (
     PLUGIN_DEBUG_KEY_ENV,
@@ -44,6 +46,39 @@ from langbot_plugin.runtime.security import (
 logger = logging.getLogger(__name__)
 
 
+class _SlotHandlerProxy:
+    """Bind every worker-to-Runtime call to one exact installation slot."""
+
+    def __init__(self, handler: PluginRuntimeHandler, binding: InstallationBinding):
+        self._handler = handler
+        self._binding = binding
+
+    async def call_action(self, action, data, timeout=15.0, **kwargs):
+        kwargs["action_context"] = self._binding
+        return await self._handler.call_action(action, data, timeout=timeout, **kwargs)
+
+    def call_action_generator(self, action, data, timeout=15.0, **kwargs):
+        kwargs["action_context"] = self._binding
+        return self._handler.call_action_generator(
+            action, data, timeout=timeout, **kwargs
+        )
+
+    async def send_file(self, file_bytes, file_extension, **kwargs):
+        kwargs["action_context"] = self._binding
+        return await self._handler.send_file(file_bytes, file_extension, **kwargs)
+
+    async def read_local_file(self, file_key, **kwargs):
+        kwargs["action_context"] = self._binding
+        return await self._handler.read_local_file(file_key, **kwargs)
+
+    async def delete_local_file(self, file_key, **kwargs):
+        kwargs["action_context"] = self._binding
+        return await self._handler.delete_local_file(file_key, **kwargs)
+
+    def __getattr__(self, name):
+        return getattr(self._handler, name)
+
+
 def _apply_runner_class_defaults(
     component_manifest: ComponentManifest,
     component_impl_cls: type[Runner],
@@ -119,6 +154,7 @@ class PluginRuntimeController:
             status=RuntimeContainerStatus.UNMOUNTED,
             components=components_containers,
         )
+        self._slot_containers: dict[str, PluginContainer] = {}
 
     async def run(self) -> None:
         await self._controller_task
@@ -167,6 +203,8 @@ class PluginRuntimeController:
 
                 async def new_connection_callback(connection: Connection):
                     self.handler = PluginRuntimeHandler(connection, self.initialize)
+                    self.handler._slot_initialize_callback = self.initialize_slot
+                    self.handler._slot_detach_callback = self.detach_slot
 
                     async def disconnect_callback(hdl: PluginRuntimeHandler):
                         if self.prod_mode:
@@ -304,18 +342,30 @@ class PluginRuntimeController:
         )
         logger.debug(f"plugin_settings: {plugin_settings}")
 
-        self.plugin_container.enabled = plugin_settings["enabled"]
-        self.plugin_container.priority = plugin_settings["priority"]
-        self.plugin_container.plugin_config = plugin_settings["plugin_config"]
+        await self._initialize_container(
+            self.plugin_container,
+            self.handler,
+            plugin_settings,
+        )
+
+    async def _initialize_container(
+        self,
+        plugin_container: PluginContainer,
+        runtime_handler: typing.Any,
+        plugin_settings: dict[str, typing.Any],
+    ) -> None:
+        """Initialize one object graph without mutating controller-global routing."""
+
+        plugin_container.enabled = plugin_settings["enabled"]
+        plugin_container.priority = plugin_settings["priority"]
+        plugin_container.plugin_config = plugin_settings["plugin_config"]
         # initialize plugin instance
-        plugin_cls = self.plugin_container.manifest.get_python_component_class()
+        plugin_cls = plugin_container.manifest.get_python_component_class()
         assert isinstance(plugin_cls, type(BasePlugin))
-        self.plugin_container.plugin_instance = plugin_cls()
-        self.plugin_container.plugin_instance.config = (
-            self.plugin_container.plugin_config
-        )
-        self.plugin_container.plugin_instance.plugin_runtime_handler = self.handler
-        await self.plugin_container.plugin_instance.initialize()
+        plugin_container.plugin_instance = plugin_cls()
+        plugin_container.plugin_instance.config = plugin_container.plugin_config
+        plugin_container.plugin_instance.plugin_runtime_handler = runtime_handler
+        await plugin_container.plugin_instance.initialize()
 
         preinitialize_component_classes: list[type[BaseComponent]] = [
             EventListener,
@@ -328,7 +378,7 @@ class PluginRuntimeController:
         ]
 
         for component_cls in preinitialize_component_classes:
-            for component_container in self.plugin_container.components:
+            for component_container in plugin_container.components:
                 logger.debug(
                     f"Checking component {component_container.manifest.metadata.name}: "
                     f"kind={component_container.manifest.kind}, expected={component_cls.__kind__}"
@@ -349,15 +399,15 @@ class PluginRuntimeController:
                             component_impl_cls,
                         )
                         component_container.component_instance.bind_runtime(
-                            plugin_runtime_handler=self.handler,
-                            plugin_config=self.plugin_container.plugin_config,
+                            plugin_runtime_handler=runtime_handler,
+                            plugin_config=plugin_container.plugin_config,
                             plugin_identity=(
-                                f"{self.plugin_container.manifest.metadata.author}/"
-                                f"{self.plugin_container.manifest.metadata.name}"
+                                f"{plugin_container.manifest.metadata.author}/"
+                                f"{plugin_container.manifest.metadata.name}"
                             ),
                         )
                     component_container.component_instance.plugin = (
-                        self.plugin_container.plugin_instance
+                        plugin_container.plugin_instance
                     )
                     await component_container.component_instance.initialize()
                     logger.info(
@@ -369,12 +419,49 @@ class PluginRuntimeController:
             f"Plugin {self.plugin_container.manifest.metadata.author}/{self.plugin_container.manifest.metadata.name} initialized"
         )
 
-        self.plugin_container.status = RuntimeContainerStatus.INITIALIZED
+        plugin_container.status = RuntimeContainerStatus.INITIALIZED
+
+    async def initialize_slot(
+        self,
+        installation_uuid: str | InstallationBinding,
+        plugin_settings: dict[str, typing.Any],
+    ) -> PluginContainer:
+        """Create or replace one installation's independent object graph."""
+
+        slot_key = (
+            installation_uuid.installation_uuid
+            if isinstance(installation_uuid, InstallationBinding)
+            else installation_uuid
+        )
+        slot = PluginContainer.from_dict(
+            copy.deepcopy(self.plugin_container.model_dump())
+        )
+        slot.plugin_instance = NonePlugin()
+        for component in slot.components:
+            component.component_instance = NoneComponent()
+        runtime_handler: typing.Any = self.handler
+        if isinstance(installation_uuid, InstallationBinding):
+            runtime_handler = _SlotHandlerProxy(self.handler, installation_uuid)
+        await self._initialize_container(slot, runtime_handler, plugin_settings)
+        self._slot_containers[slot_key] = slot
+        return slot
+
+    def plugin_container_for_slot(
+        self,
+        installation_uuid: str,
+    ) -> PluginContainer | None:
+        return self._slot_containers.get(installation_uuid)
+
+    async def detach_slot(self, installation_uuid: str) -> None:
+        """Drop exactly one slot; sibling instances remain resident."""
+
+        self._slot_containers.pop(installation_uuid, None)
 
     async def cleanup_instances(self) -> None:
         """Clean up all plugin and component instances."""
         logger.info("Cleaning up plugin instances...")
 
+        self._slot_containers.clear()
         # Clear component instances
         for component_container in self.plugin_container.components:
             # Reset component instance

{langbot_plugin-0.6.1b2 → langbot_plugin-0.6.3}/src/langbot_plugin/cli/run/handler.py

@@ -19,6 +19,7 @@ from langbot_plugin.api.definition.components.base import NoneComponent
 from langbot_plugin.api.definition.components.common.event_listener import EventListener
 from langbot_plugin.entities.io.actions.enums import PluginToRuntimeAction
 from langbot_plugin.entities.io.actions.enums import RuntimeToPluginAction
+from langbot_plugin.entities.io.context import InstallationBinding
 from langbot_plugin.api.definition.components.tool.tool import Tool
 from langbot_plugin.api.definition.components.command.command import Command
 from langbot_plugin.api.definition.components.knowledge_engine.engine import (
@@ -138,7 +139,7 @@ async def _iter_runner_results_with_deadline(
 class PluginRuntimeHandler(Handler):
     """The handler for running plugins."""
 
-    plugin_container: PluginContainer
+    _base_plugin_container: PluginContainer
 
     shutdown_callback: (
         typing.Callable[[], typing.Coroutine[typing.Any, typing.Any, None]] | None
@@ -155,6 +156,18 @@ class PluginRuntimeHandler(Handler):
         super().__init__(connection)
         self.name = "FromRuntime"
         self._shutdown_task: asyncio.Task[None] | None = None
+        self._slot_containers: dict[str, PluginContainer] = {}
+        self._slot_initialize_callback: (
+            typing.Callable[
+                [InstallationBinding, dict[str, typing.Any]],
+                typing.Coroutine[typing.Any, typing.Any, PluginContainer],
+            ]
+            | None
+        ) = None
+        self._slot_detach_callback: (
+            typing.Callable[[str], typing.Coroutine[typing.Any, typing.Any, None]]
+            | None
+        ) = None
 
         @self.action(RuntimeToPluginAction.INITIALIZE_PLUGIN)
         async def initialize_plugin(data: dict[str, typing.Any]) -> ActionResponse:
@@ -164,6 +177,44 @@ class PluginRuntimeHandler(Handler):
             await plugin_initialize_callback(data["plugin_settings"])
             return ActionResponse.success({})
 
+        @self.action(RuntimeToPluginAction.ATTACH_PLUGIN_SLOT)
+        async def attach_plugin_slot(data: dict[str, typing.Any]) -> ActionResponse:
+            binding = self.current_action_context
+            if not isinstance(binding, InstallationBinding):
+                raise ValueError("Shared slot attach requires InstallationBinding")
+            if self._slot_initialize_callback is None:
+                raise ValueError("Shared slot initialization is unavailable")
+            container = await self._slot_initialize_callback(
+                binding,
+                data["plugin_settings"],
+            )
+            self._slot_containers[binding.installation_uuid] = container
+            return ActionResponse.success({})
+
+        @self.action(RuntimeToPluginAction.DETACH_PLUGIN_SLOT)
+        async def detach_plugin_slot(data: dict[str, typing.Any]) -> ActionResponse:
+            del data
+            binding = self.current_action_context
+            if not isinstance(binding, InstallationBinding):
+                raise ValueError("Shared slot detach requires InstallationBinding")
+            if self._slot_detach_callback is not None:
+                await self._slot_detach_callback(binding.installation_uuid)
+            self._slot_containers.pop(binding.installation_uuid, None)
+            return ActionResponse.success({})
+
+        @self.action(RuntimeToPluginAction.GET_PLUGIN_SLOT_CONTAINER)
+        async def get_plugin_slot_container(
+            data: dict[str, typing.Any],
+        ) -> ActionResponse:
+            del data
+            binding = self.current_action_context
+            if not isinstance(binding, InstallationBinding):
+                raise ValueError("Shared slot lookup requires InstallationBinding")
+            container = self._slot_containers.get(binding.installation_uuid)
+            if container is None:
+                raise ValueError("Shared plugin slot is not attached")
+            return ActionResponse.success(container.model_dump())
+
         @self.action(RuntimeToPluginAction.GET_PLUGIN_CONTAINER)
         async def get_plugin_container(data: dict[str, typing.Any]) -> ActionResponse:
             return ActionResponse.success(self.plugin_container.model_dump())
@@ -713,6 +764,19 @@ class PluginRuntimeHandler(Handler):
 
             return ActionResponse.success(result.model_dump(mode="json"))
 
+    @property
+    def plugin_container(self) -> PluginContainer:
+        binding = self.current_action_context
+        if isinstance(binding, InstallationBinding):
+            slot = self._slot_containers.get(binding.installation_uuid)
+            if slot is not None:
+                return slot
+        return self._base_plugin_container
+
+    @plugin_container.setter
+    def plugin_container(self, value: PluginContainer) -> None:
+        self._base_plugin_container = value
+
     async def register_plugin(
         self,
         prod_mode: bool = False,

{langbot_plugin-0.6.1b2 → langbot_plugin-0.6.3}/src/langbot_plugin/entities/io/actions/enums.py

@@ -134,6 +134,9 @@ class RuntimeToPluginAction(ActionType):
     """The action from runtime to plugin."""
 
     INITIALIZE_PLUGIN = "initialize_plugin"
+    ATTACH_PLUGIN_SLOT = "attach_plugin_slot"
+    DETACH_PLUGIN_SLOT = "detach_plugin_slot"
+    GET_PLUGIN_SLOT_CONTAINER = "get_plugin_slot_container"
     GET_PLUGIN_CONTAINER = "get_plugin_container"
     GET_PLUGIN_ICON = "get_plugin_icon"
     GET_PLUGIN_README = "get_plugin_readme"

{langbot_plugin-0.6.1b2 → langbot_plugin-0.6.3}/src/langbot_plugin/entities/io/context.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import json
 import math
 import re
+from enum import Enum
 from typing import Literal
 
 import pydantic
@@ -11,6 +12,13 @@ import pydantic
 _SHA256_DIGEST_PATTERN = re.compile(r"^[0-9a-f]{64}$")
 
 
+class PluginExecutionMode(str, Enum):
+    """Process placement selected by the trusted control plane."""
+
+    DEDICATED = "dedicated"
+    SHARED_CERTIFIED = "shared-runtime-v1"
+
+
 class RuntimeIdentity(pydantic.BaseModel):
     """Stable instance scope plus this Runtime process' short-lived identity."""
 
@@ -333,6 +341,7 @@ class PluginInstallationDesiredState(pydantic.BaseModel):
 
     binding: InstallationBinding
     enabled: bool = True
+    execution_mode: PluginExecutionMode = PluginExecutionMode.DEDICATED
 
     model_config = pydantic.ConfigDict(extra="forbid", frozen=True)
 
@@ -364,6 +373,7 @@ class ReconcilePluginInstallationsRequest(pydantic.BaseModel):
 class ApplyPluginInstallationRequest(pydantic.BaseModel):
     artifact_file_key: str | None = None
     enabled: bool = True
+    execution_mode: PluginExecutionMode = PluginExecutionMode.DEDICATED
 
     model_config = pydantic.ConfigDict(extra="forbid", frozen=True)