langbot-plugin 0.7.4__tar.gz → 0.7.6__tar.gz

{langbot_plugin-0.7.4 → langbot_plugin-0.7.6}/ARCHITECTURE.md

@@ -59,7 +59,9 @@ Plugin-facing APIs live under `src/langbot_plugin/api/`.
 - `certification.py` defines optional ZIP-comment certification envelopes. It
   canonicalizes envelope JSON, normalizes the ZIP digest by removing the comment,
   and verifies the signed manifest identity and runtime profile without changing
-  legacy archive output.
+  unsigned archive output. New certificates exist only for Cloud cross-tenant
+  sharing of one Worker and one plugin/component singleton, not dedicated mode;
+  older v1 claims without signed stateless component model cannot authorize sharing.
 - `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.
 
@@ -220,7 +222,7 @@ may select indexes or trusted hosts.
 
 The dependency admission path has one bounded historical ABI exception: nine
 explicit `langbot-team` archive identities with exact raw SHA-256 digests and
-`langbot-plugin==0.6.1` may use the Runtime-owned SDK **0.7.4** in `dedicated`
+`langbot-plugin==0.6.1` may use the Runtime-owned SDK **0.7.6** in `dedicated`
 mode only. Artifact bytes are verified before extraction; a changed archive,
 identity, requirement, Runtime version, or shared execution mode fails normal
 SDK pin validation. This does not issue a certificate or change Core placement

{langbot_plugin-0.7.4 → langbot_plugin-0.7.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: langbot-plugin
-Version: 0.7.4
+Version: 0.7.6
 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.4 → langbot_plugin-0.7.6}/docs/certified-plugins.md

@@ -1,6 +1,6 @@
 # Certified Plugin Archives
 
-`langbot_plugin.certification` provides an opt-in archive certification format. It does not change `lbp build` output: existing `.lbpkg` archives retain an empty ZIP comment and verify as `absent`.
+`langbot_plugin.certification` provides an opt-in archive certification format **only for Cloud cross-tenant sharing of the same Worker and the same plugin/component singleton**. It does not change `lbp build` output: unsigned `.lbpkg` archives retain an empty ZIP comment and verify as `absent`; Cloud installs them on dedicated Workers. There is no dedicated certificate or intermediate trust tier.
 
 ## Manifest runtime profile
 
@@ -34,11 +34,11 @@ The envelope is compact, sorted UTF-8 JSON in the ZIP comment. New stateless cer
 }
 ```
 
-`shared_runtime` is `null` for dedicated-runtime manifests. The digest is SHA-256 of the original ZIP bytes with only its ZIP comment removed, so adding or replacing the envelope does not change the signed digest. ZIP comments are limited to 16 KiB; archive manifests are read without extraction and limited to 1 MiB.
+New v2 envelopes require `shared_runtime: shared-runtime-v1` and `component_model: stateless-v1`. Dedicated manifests must remain unsigned; historical v2 envelopes with null claims do not verify as certification. Older v1 schemas may carry null claims, but cannot grant Cloud sharing or be treated as unsigned. The digest is SHA-256 of the original ZIP bytes with only its ZIP comment removed, so adding or replacing the envelope does not change the signed digest. ZIP comments are limited to 16 KiB; archive manifests are read without extraction and limited to 1 MiB.
 
 ## Signing and verification
 
-The module is algorithm-neutral and does not add a cryptography dependency. Supply the signing callback and a trusted-key resolver from the deployment that owns issuer keys. Production integrations should use an asymmetric signature scheme such as Ed25519; do not use the test-only HMAC pattern as a trust boundary.
+The module is algorithm-neutral and does not add a cryptography dependency. Supply the signing callback and a trusted-key resolver from the deployment that owns issuer keys. Cloud issuers use Ed25519. OSS ships without a built-in issuer public key, supports one Workspace, and does not support configuring a certification key or shared-certified execution. Do not use the test-only HMAC pattern as a trust boundary.
 
 ```python
 from langbot_plugin.certification import create_envelope, verify_archive, write_envelope
@@ -53,7 +53,7 @@ if result.status != "valid":
     raise ValueError(result.status)
 ```
 
-Verification binds the envelope's `plugin_id.author`, `plugin_id.name`, `version`, normalized digest, `shared_runtime`, and `component_model` to `manifest.yaml`.
+Verification binds the envelope's `plugin_id.author`, `plugin_id.name`, `version`, normalized digest, `shared_runtime`, and `component_model` to `manifest.yaml`. Legacy v1 signatures can still verify cryptographically but never grant singleton sharing because they lack the signed `stateless-v1` claim. Malformed or untrusted signatures are not unsigned archives and Cloud must reject them. Verification alone is not placement: compare the exact downloaded artifact, public version record and deployed Core trust ring. A reviewed source candidate, `issued` badge, or shared code/dependency tree does not prove a live shared Worker.
 
 ## Verification statuses
 

{langbot_plugin-0.7.4 → langbot_plugin-0.7.6}/docs/stateless-components.md

@@ -13,7 +13,7 @@ execution:
   componentModel: stateless-v1
 ```
 
-`sharedRuntime` without `componentModel: stateless-v1` is not eligible for certification. Legacy source and unsigned packages remain compatible with the dedicated path. OSS may downgrade an untrusted or legacy certificate to dedicated according to its admission policy; Cloud may reject it before installation.
+`sharedRuntime` without `componentModel: stateless-v1` is not eligible for certification. Legacy source and unsigned packages remain compatible with the dedicated path. OSS ships no built-in issuer public key and supports dedicated execution only; configuring a certification key on OSS is unsupported. Cloud rejects an untrusted or legacy signed certificate rather than treating it as unsigned.
 
 ## Programming contract
 
@@ -25,11 +25,40 @@ execution:
 - Use SDK Host APIs for tenant storage, credentials, files, logging, models, tools, and RAG. Authority comes from the task-local `InstallationBinding`.
 - If identity is needed, call `get_installation_binding()` during an invocation. Do not retain it after the call returns.
 - Components must be re-entrant: invocations from different Workspaces may overlap on the same object.
-- Tenant-bearing background work is forbidden in `stateless-v1` until the SDK exposes an explicit ownership and revocation API. Do not create tenant-bearing threads or detached tasks in `initialize()` or an invocation.
-- Process-level caches may contain only public/artifact-level data. Tenant caches must include the full installation binding and be explicitly released on revocation.
+- The SDK does not track ownership of tasks you create. If you detach tenant-bearing work, keep your own registry keyed by the full installation binding and stop it in `on_installation_revoked` before returning.
+- Process-level caches may contain only public/artifact-level data. A cache that holds tenant state must include the full installation binding and be released in `BasePlugin.on_installation_revoked()`.
 
 This contract deliberately matches a future serverless execution model: component methods depend on input plus invocation context, while tenant state remains in Host services. The current release still uses long-lived workers; it does not provide a serverless deployment mode.
 
+## Installation revocation
+
+One object graph serves every installation of an artifact digest and is never
+destroyed per installation, so releasing binding-keyed process state is the
+plugin's own responsibility:
+
+```python
+class MyPlugin(BasePlugin):
+    def __init__(self) -> None:
+        super().__init__()
+        self._caches: dict[str, Cache] = {}
+
+    async def on_installation_revoked(self, binding: InstallationBinding) -> None:
+        self._caches.pop(binding.installation_uuid, None)
+```
+
+The runtime calls this once per installation, after cancelling that
+installation's in-flight messages and detaching its slot. It fires for
+uninstall, disable, Workspace removal and upgrade (the superseded binding is
+revoked when the new revision activates). Dedicated workers are shut down
+instead of detached, so this hook runs for shared placement only; dedicated
+state disappears with the process.
+
+There is no active invocation during the call, so Host APIs (storage, config,
+binding lookups) are unavailable and only the `binding` argument identifies the
+installation. Return `None`; exceptions are logged and never block revocation.
+Calls are serialized per installation but may overlap with invocations of
+sibling installations on the same object graph.
+
 ## Example
 
 ```python
@@ -56,4 +85,4 @@ Shared initialization has no tenant config, so this captures empty/stale data or
 
 ## Compatibility
 
-Legacy source and unsigned packages keep the dedicated worker and existing object/config semantics. In OSS, certificate failures may downgrade to dedicated according to admission policy; Cloud may reject an ineligible package before storage. The stateless rules are an opt-in certification contract. Adding only the manifest fields is insufficient: source review and concurrency tests must prove the implementation follows the contract.
+Legacy source and unsigned packages keep the dedicated worker and existing object/config semantics. OSS is dedicated-only and has no supported certification key configuration. Cloud must reject an invalid or legacy signed archive rather than treating it as unsigned. The stateless rules are an opt-in certification contract. Adding only the manifest fields is insufficient: source review and concurrency tests must prove the implementation follows the contract.

{langbot_plugin-0.7.4 → langbot_plugin-0.7.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langbot-plugin"
-version = "0.7.4"
+version = "0.7.6"
 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.6/src/langbot_plugin/api/definition/plugin.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import abc
+import typing
+
+from langbot_plugin.api.proxies import langbot_api
+from langbot_plugin.api.proxies.invocation import current_binding, current_config
+
+if typing.TYPE_CHECKING:
+    from langbot_plugin.entities.io.context import InstallationBinding
+
+
+class BasePlugin(abc.ABC, langbot_api.LangBotAPIProxy):
+    """The base class for all plugins."""
+
+    _legacy_config: dict[str, typing.Any]
+
+    @property
+    def config(self) -> dict[str, typing.Any]:
+        """Expose task-local config while preserving dedicated plugin behavior."""
+
+        scoped = current_config(getattr(self, "plugin_runtime_handler", None))
+        if scoped is not None:
+            return dict(scoped)
+        return getattr(self, "_legacy_config", {})
+
+    @config.setter
+    def config(self, value: dict[str, typing.Any]) -> None:
+        self._legacy_config = dict(value)
+
+    def get_config(self) -> dict[str, typing.Any]:
+        """Return the active invocation config, or the legacy dedicated config."""
+
+        return self.config
+
+    def get_installation_binding(self):
+        """Return the active certified installation binding, if any."""
+
+        return current_binding(getattr(self, "plugin_runtime_handler", None))
+
+    def __init__(self):
+        self._legacy_config = {}
+
+    async def initialize(self) -> None:
+        pass
+
+    async def on_installation_revoked(self, binding: InstallationBinding) -> None:
+        """Release process-local state held for one revoked installation.
+
+        The runtime calls this once per installation, after that installation's
+        in-flight messages have been cancelled and its slot detached, and before
+        anything else may reuse the object graph. Shared placement calls it for
+        uninstall, disable, workspace removal and upgrade (the superseded binding
+        is revoked when the new revision activates). Dedicated workers are shut
+        down instead of detached, so their process-local state disappears with
+        the process and this hook is not called.
+
+        Shared-runtime plugins must drop every cache or registry entry keyed by
+        this binding here: one object graph serves every installation of the
+        artifact digest and is never destroyed per installation.
+
+        There is no active invocation, so Host APIs (storage, config, binding
+        lookups) are unavailable. Only process-local state can be touched, and
+        only the given `binding` identifies the installation. Return `None`;
+        exceptions are logged and never block revocation. The call is serialized
+        per installation but may overlap with invocations of sibling
+        installations on the same object graph.
+        """
+
+        return None
+
+    def __del__(self) -> None:
+        pass
+
+
+class NonePlugin(BasePlugin):
+    """The plugin that does nothing, just acts as a placeholder."""
+
+    def __init__(self):
+        super().__init__()

{langbot_plugin-0.7.4 → langbot_plugin-0.7.6}/src/langbot_plugin/certification.py

@@ -93,6 +93,13 @@ def create_envelope(
 ) -> CertificationEnvelope:
     """Create a signed envelope bound to the archive digest and manifest identity."""
     identity = _read_manifest_identity(archive)
+    if (
+        identity["shared_runtime"] != "shared-runtime-v1"
+        or identity["component_model"] != "stateless-v1"
+    ):
+        raise EnvelopeFormatError(
+            "certification requires sharedRuntime shared-runtime-v1 and componentModel stateless-v1"
+        )
     unsigned = CertificationEnvelope(
         schema=CERTIFICATION_SCHEMA,
         key_id=_required_string(key_id, "key_id"),
@@ -190,6 +197,11 @@ def verify_archive(
         return CertificationVerification("absent")
     if envelope.schema not in {CERTIFICATION_SCHEMA, LEGACY_CERTIFICATION_SCHEMA}:
         return CertificationVerification("unsupported_schema", envelope)
+    if envelope.schema == CERTIFICATION_SCHEMA and (
+        envelope.shared_runtime != "shared-runtime-v1"
+        or envelope.component_model != "stateless-v1"
+    ):
+        return CertificationVerification("malformed", envelope)
     try:
         if normalized_zip_digest(archive) != envelope.digest:
             return CertificationVerification("digest_mismatch", envelope)
@@ -253,6 +265,13 @@ def _validate_envelope(
         raise EnvelopeFormatError("certification envelope shared_runtime is invalid")
     if envelope.component_model not in {None, "stateless-v1"}:
         raise EnvelopeFormatError("certification envelope component_model is invalid")
+    if envelope.schema == CERTIFICATION_SCHEMA and (
+        envelope.shared_runtime != "shared-runtime-v1"
+        or envelope.component_model != "stateless-v1"
+    ):
+        raise EnvelopeFormatError(
+            "certification requires shared-runtime-v1 and stateless-v1"
+        )
     if (
         envelope.shared_runtime == "shared-runtime-v1"
         and envelope.component_model != "stateless-v1"

{langbot_plugin-0.7.4 → langbot_plugin-0.7.6}/src/langbot_plugin/cli/__init__.py

@@ -86,6 +86,12 @@ def main():
         help="Comma-separated trusted hosts for plugin dependency installation",
         default="",
     )
+    run_parser.add_argument(
+        "--tag",
+        type=str,
+        help="Process label shown by ps/htop (for example author/plugin_name); cosmetic only",
+        default="",
+    )
 
     # login command
     login_parser = subparsers.add_parser("login", help="Login to LangBot account")
@@ -191,6 +197,7 @@ def main():
                 args.plugin_debug_key,
                 args.pypi_index_url,
                 args.pypi_trusted_host,
+                tag=args.tag,
             )
         case "build":
             build_plugin_process(args.output)

{langbot_plugin-0.7.4 → langbot_plugin-0.7.6}/src/langbot_plugin/cli/commands/runplugin.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import dotenv
+import logging
 import os
 
 from langbot_plugin.utils.discover.engine import ComponentDiscoveryEngine
@@ -18,10 +19,32 @@ from langbot_plugin.runtime.bounded_executor import (
 )
 
 
+logger = logging.getLogger(__name__)
+
+
 def should_load_artifact_dotenv(runtime_profile: str) -> bool:
     return runtime_profile != "shared"
 
 
+def apply_process_label(tag: str) -> None:
+    """Record the process label carried by the worker command line.
+
+    The launcher passes ``--tag author/name`` so an operator can tell which
+    plugin a worker belongs to from ps/htop; this helper keeps the same value in
+    the worker log. It makes no syscalls and changes no process attribute, so it
+    behaves identically on every platform.
+
+    The label is cosmetic only: it is never an identity, an authorization input
+    or a routing key. The Runtime owns the real installation identity, and this
+    value may be forged by whoever starts the process.
+    """
+
+    label = "".join(ch for ch in str(tag or "") if ch.isprintable()).strip()
+    if not label:
+        return
+    logger.info("Plugin worker process label: %s", label)
+
+
 async def arun_plugin_process(
     stdio: bool = False,
     prod_mode: bool = False,
@@ -93,8 +116,10 @@ def run_plugin_process(
     plugin_debug_key: str = "",
     pypi_index_url: str = "",
     pypi_trusted_host: str = "",
+    tag: str = "",
 ) -> None:
     configure_process_logging()
+    apply_process_label(tag)
 
     try:
         asyncio.run(

{langbot_plugin-0.7.4 → langbot_plugin-0.7.6}/src/langbot_plugin/cli/run/controller.py

@@ -48,6 +48,37 @@ from langbot_plugin.runtime.security import (
 logger = logging.getLogger(__name__)
 
 
+async def notify_installation_revoked(
+    plugin_container: PluginContainer,
+    binding: InstallationBinding,
+) -> None:
+    """Let a plugin release process-local state held for one installation.
+
+    One object graph is shared by every installation of an artifact digest and is
+    never destroyed per installation, so a revoked installation's in-process state
+    is only released here. Dedicated workers are shut down instead of detached, so
+    this runs for shared placement.
+
+    There is no active invocation, so per-invocation APIs (Host storage, config
+    and binding lookups) are unavailable; the hook may only touch process-local
+    state. Failures are logged and never block revocation.
+    """
+
+    if plugin_container.status is not RuntimeContainerStatus.INITIALIZED:
+        return
+    hook = getattr(plugin_container.plugin_instance, "on_installation_revoked", None)
+    if hook is None:
+        return
+    try:
+        await hook(binding)
+    except Exception as exc:
+        logger.warning(
+            "Plugin on_installation_revoked failed for installation %s: %s",
+            binding.installation_uuid,
+            exc,
+        )
+
+
 class _SlotHandlerProxy:
     """Bind every worker-to-Runtime call to one exact installation slot."""
 
@@ -485,7 +516,13 @@ class PluginRuntimeController:
         """Drop exactly one slot; sibling instances remain resident."""
 
         self.invalidate_slot(installation_uuid)
-        self._slot_containers.pop(installation_uuid, None)
+        slot = self._slot_containers.pop(installation_uuid, None)
+        if slot is None:
+            return
+        # The slot is no longer routable while the object graph stays resident for
+        # sibling installations, so this is the only chance to release state the
+        # plugin keyed by the revoked binding.
+        await notify_installation_revoked(self.plugin_container, slot.binding)
 
     async def cleanup_instances(self) -> None:
         """Clean up all plugin and component instances."""