langbot-plugin 0.5.0a2__tar.gz → 0.5.2__tar.gz

langbot_plugin-0.5.2/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "[0-9]+.[0-9]+.[0-9]+"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Build distributions
+        run: uv build
+      - name: Publish to PyPI
+        run: uv publish --token "$UV_PUBLISH_TOKEN"
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}

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

@@ -0,0 +1,93 @@
+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 \
+            --ignore=tests/packaging \
+            --cov=langbot_plugin \
+            --cov-report=term-missing \
+            --cov-fail-under=84
+
+  test-lint:
+    name: Lint and Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Ruff check
+        run: uv run ruff check src tests --output-format=concise
+      - name: Ruff format check
+        run: uv run ruff format --check src tests
+
+  package-smoke:
+    name: Package Smoke
+    runs-on: ubuntu-latest
+    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 3.12
+      - name: Installed wheel CLI smoke
+        run: uv run --python 3.12 pytest -q tests/packaging
+
+  scoped-type-check:
+    name: Scoped Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Mypy stable protocol modules
+        run: |
+          uv run mypy \
+            src/langbot_plugin/entities/io \
+            src/langbot_plugin/runtime/plugin/logbuffer.py \
+            src/langbot_plugin/utils/platform.py
+
+  action-consistency:
+    name: Action Protocol Consistency
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check action enum / proxy / handler consistency
+        run: python scripts/check_action_consistency.py

langbot_plugin-0.5.2/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.5.2/ARCHITECTURE.md

@@ -0,0 +1,378 @@
+# 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": {} }
+```
+
+Tenant-scoped control actions must carry a complete, trusted installation
+binding without placing authority in the action payload:
+
+```json
+{
+  "seq_id": 1,
+  "action": "action_name",
+  "data": {},
+  "context": {
+    "instance_uuid": "instance-id",
+    "workspace_uuid": "workspace-id",
+    "placement_generation": 1,
+    "installation_uuid": "installation-id",
+    "runtime_revision": 1,
+    "artifact_digest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+  }
+}
+```
+
+`SET_RUNTIME_CONFIG` is the instance-scoped handshake. It carries no Workspace
+context and accepts this frozen payload:
+
+```json
+{
+  "runtime_identity": {
+    "instance_uuid": "instance-id",
+    "runtime_id": "short-lived-runtime-id"
+  },
+  "worker_policy": {
+    "max_cpus": 1.0,
+    "max_memory_mb": 512,
+    "max_pids": 128,
+    "max_open_files": 256,
+    "max_file_size_mb": 512,
+    "max_concurrent_restarts": 1,
+    "restart_failure_threshold": 8,
+    "restart_failure_window_seconds": 30.0,
+    "restart_circuit_open_seconds": 60.0,
+    "require_hard_limits": true
+  },
+  "runtime_profile": "shared",
+  "cloud_service_url": "https://space.langbot.app"
+}
+```
+
+The Runtime identity and worker policy can be repeated exactly after a control
+reconnect but cannot be changed for the life of the Runtime process. A new
+authenticated control handler atomically supersedes the old handler; old
+requests fail even if the old transport has not finished closing.
+
+After the handshake, every tenant-scoped LangBot-to-Runtime action (including
+file chunks) requires the complete immutable tuple
+`(instance_uuid, workspace_uuid, placement_generation, installation_uuid,
+runtime_revision, artifact_digest)`. Missing context, a different instance, or
+an attempted generation/revision/artifact rebind fails closed. Instance-scoped
+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`
+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.
+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
+reconnect restore the authoritative desired set.
+
+Restart attempts also pass through one Runtime-wide coordinator. Launches are
+globally bounded until a worker completes initialization; repeated unexpected
+exits in the configured window open a circuit. After cooldown, exactly one
+half-open probe may launch, and it must remain stable before the circuit closes.
+A child that does not become ready within 30 seconds is cancelled and reaped.
+Aggregate coordinator counters are exposed through Runtime health without
+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.
+
+Before a shared worker is launched, the Runtime prepares dependencies in a
+separate nsjail. The resulting `site-packages` tree is keyed by the verified
+artifact, requirements bytes, Python ABI, Runtime version, and installer schema,
+then atomically published under `environments/sha256/<environment-digest>`.
+Concurrent installations reuse the same ready tree. Workers mount it read-only;
+failed or partial preparations are removed and reported as the 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
+PID limits plus file/process rlimits. If `require_hard_limits` is true, missing
+nsjail or cgroup v2 delegation makes configuration fail closed. Artifact `.env`
+files are not loaded in the shared profile. The default `oss_dev` profile keeps
+the direct-process and `.env` behavior needed for local open-source development.
+The Runtime waits for this immutable profile handshake before inspecting legacy
+plugin state. A shared Runtime never scans, installs dependencies for, or
+launches the global `data/plugins` tree; only apply/reconcile desired state may
+start an installation worker.
+
+Response shape:
+
+```json
+{ "seq_id": 1, "code": 0, "message": "success", "data": {}, "chunk_status": "continue" }
+```
+
+Core mechanics:
+
+- `seq_id` correlates responses to requests.
+- `context` carries trusted tenant/installation authority independently of
+  plugin-controlled `data`; it is mandatory on tenant control actions.
+- 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/`. Transfer keys are high-entropy opaque basenames; the
+  receiver rejects absolute paths, separators, `..`, and unsafe extensions.
+
+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 plugin processes do not authenticate with the shared debug key. For
+each child launch, the Runtime reads the installed `manifest.yaml`, issues a
+short-lived one-use registration capability bound to that author/name, and
+passes only that capability to the child. The capability is consumed before
+Host settings are requested, cannot be replayed, and the plugin must preserve
+the same manifest identity after initialization. On Windows the child receives
+an explicit environment allowlist, so Runtime and Box control secrets are not
+inherited.
+
+WebSocket control may use the high-entropy
+`LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN` in the
+`X-LangBot-Plugin-Runtime-Token` handshake header. OSS defaults to no control
+token when both LangBot and Runtime leave it unset; if either side configures
+one, both sides must use the same value. The debug server instead accepts only
+Workspace-scoped random credentials issued through the authenticated control
+channel. Each Workspace gets a different token, valid for two hours, and
+`lbp run` sends it in the `X-LangBot-Plugin-Debug-Key` handshake header
+sessions. Windows production children use their one-use registration
+capability in `X-LangBot-Plugin-Registration-Capability` instead. The
+instance-scoped `SET_RUNTIME_CONFIG` handshake and per-action installation
+bindings are authorization fences after transport authentication; neither is a
+substitute for authenticating the peer.
+
+Legacy OSS 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. Shared workers instead use the digest-addressed
+artifact tree and installation-private paths described above. RPC transfer files
+created inside a shared worker use its private writable tmp mount; files accepted
+by the Supervisor are stored in an installation-private Runtime directory and
+enforce the instance file-size policy.
+
+## 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.
+
+Box keeps durable skill/storage paths in an `(instance, workspace)` namespace,
+while 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
+generation in authenticated headers; an attached relay closes as soon as that
+generation becomes stale.
+
+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.
+
+Workspace action-context support starts in SDK `0.4.15`. The instance-scoped
+Runtime handshake and complete `InstallationBinding` extend that protocol on
+the multi-tenant branch and require a coordinated LangBot Core change before
+release. Until a matching SDK version is published, Core must pin the exact
+pushed SDK commit; the already-published `0.4.14` artifact does not contain any
+of these contracts and must not be used as a compatibility alias.
+
+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.