berthos-sdk 0.2.1__py3-none-any.whl

berth_sdk/__init__.py

@@ -0,0 +1,13 @@
+from .app import AppContext, BerthApp, define_app
+from .manifest import BerthManifest, ExportSpec, load_manifest, matches_capability, parse_capability
+
+__all__ = [
+    "AppContext",
+    "BerthApp",
+    "define_app",
+    "BerthManifest",
+    "ExportSpec",
+    "load_manifest",
+    "matches_capability",
+    "parse_capability",
+]

berth_sdk/app.py

@@ -0,0 +1,65 @@
+"""Mirrors @berthos/sdk's app.ts (defineApp/BerthApp/ExportDefinition). Python
+has no default-export convention, so the equivalent authoring pattern is a
+module-level `app = define_app(...)` — runtime.py looks for that attribute
+name on the imported app module.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Optional
+
+from .manifest import BerthManifest
+
+
+@dataclass
+class ExportDefinition:
+    name: str
+    handler: Callable[[Any], Any]
+    # Optional pydantic BaseModel subclasses — validated the same way zod
+    # schemas validate input/output in the TS SDK's ExportDefinition.
+    input_model: Optional[type] = None
+    output_model: Optional[type] = None
+
+
+class AppContext:
+    """Semantic-fs's tag/query control API is deliberately out of scope for
+    this SDK — see docs/sdk-python-reference.md. Direct file I/O against the
+    FUSE-mounted /context already works from any process with zero SDK code,
+    which is this SDK's honest v1 scope for context access. `context_bus` is
+    real (see context_bus.py / local_context_bus.py, wired in by
+    runtime.py)."""
+
+    def __init__(self, manifest: BerthManifest, context_bus: Any) -> None:
+        self.manifest = manifest
+        self.context_bus = context_bus
+
+
+class BerthApp:
+    def __init__(self) -> None:
+        self.exports: dict[str, ExportDefinition] = {}
+        self.on_install_hooks: list[Callable[[], None]] = []
+        self.on_agent_ready_hooks: list[Callable[[AppContext], None]] = []
+
+    def export(
+        self,
+        name: str,
+        handler: Callable[[Any], Any],
+        input_model: Optional[type] = None,
+        output_model: Optional[type] = None,
+    ) -> None:
+        if name in self.exports:
+            raise ValueError(f'export "{name}" is already registered')
+        self.exports[name] = ExportDefinition(name, handler, input_model, output_model)
+
+    def on_install(self, fn: Callable[[], None]) -> None:
+        self.on_install_hooks.append(fn)
+
+    def on_agent_ready(self, fn: Callable[[AppContext], None]) -> None:
+        self.on_agent_ready_hooks.append(fn)
+
+
+def define_app(setup: Callable[[BerthApp], None]) -> BerthApp:
+    app = BerthApp()
+    setup(app)
+    return app

berth_sdk/context_bus.py

@@ -0,0 +1,114 @@
+"""Real context-bus client — talks to the same Rust daemon @berthos/sdk's
+unix-socket.ts does, over the same wire contract: a Unix socket carrying
+length-prefixed (4-byte big-endian length + protobuf bytes) Envelope frames,
+per proto/context_bus.proto. Unlike rpc.py's protocol (plain newline-JSON,
+reused as-is), this one needs real protobuf codegen — see
+scripts/gen_proto.sh for how context_bus_pb2.py is generated, and why
+`python3 -m grpc_tools.protoc` is used instead of a bare system `protoc`
+(version-compatibility reasons documented there).
+"""
+
+from __future__ import annotations
+
+import json
+import socket
+import threading
+import time
+from collections import defaultdict
+from typing import Any, Callable, Optional
+
+from . import context_bus_pb2 as pb
+
+CONNECT_TIMEOUT_S = 2.0
+CONNECT_RETRY_INTERVAL_S = 0.1
+
+
+class ContextBusClient:
+    """Same interface shape as @berthos/sdk's ContextBusClient
+    (register/publish/subscribe) — resident app code doesn't change based on
+    which implementation runtime.py wires in, matching the TS SDK's own
+    local-vs-real symmetry."""
+
+    def __init__(self, sock: socket.socket) -> None:
+        self._sock = sock
+        self._lock = threading.Lock()
+        self._handlers: dict[str, list[Callable[[Any], None]]] = defaultdict(list)
+        self._read_buffer = b""
+        self._reader_thread = threading.Thread(target=self._read_loop, daemon=True)
+        self._reader_thread.start()
+
+    def _read_loop(self) -> None:
+        while True:
+            try:
+                chunk = self._sock.recv(4096)
+            except OSError:
+                return
+            if not chunk:
+                return
+            self._read_buffer += chunk
+            while len(self._read_buffer) >= 4:
+                length = int.from_bytes(self._read_buffer[:4], "big")
+                if len(self._read_buffer) < 4 + length:
+                    break
+                frame = self._read_buffer[4 : 4 + length]
+                self._read_buffer = self._read_buffer[4 + length :]
+                self._handle_frame(frame)
+
+    def _handle_frame(self, frame: bytes) -> None:
+        envelope = pb.Envelope()
+        envelope.ParseFromString(frame)
+        if envelope.HasField("event"):
+            topic = envelope.event.topic
+            raw_payload = envelope.event.payload
+            payload = json.loads(raw_payload.decode("utf-8")) if raw_payload else None
+            for handler in list(self._handlers.get(topic, [])):
+                handler(payload)
+
+    def _send(self, **kwargs: Any) -> None:
+        envelope = pb.Envelope(**kwargs)
+        encoded = envelope.SerializeToString()
+        with self._lock:
+            self._sock.sendall(len(encoded).to_bytes(4, "big") + encoded)
+
+    # Plain synchronous methods, not `async def` — unlike the TS SDK
+    # (Node's I/O model makes everything naturally async), this runtime has
+    # no event loop: app hooks are called as plain sync functions, and the
+    # underlying socket write is already a blocking sendall(). Making these
+    # `async def` would just produce un-awaited coroutine objects that never
+    # actually run when called from a sync hook.
+    def register(self, app: str) -> None:
+        self._send(register=pb.RegisterRequest(app=app))
+
+    def publish(self, topic: str, payload: Any) -> None:
+        encoded_payload = json.dumps(payload if payload is not None else None).encode("utf-8")
+        self._send(publish=pb.PublishRequest(topic=topic, payload=encoded_payload))
+
+    def subscribe(self, topic: str, handler: Callable[[Any], None]) -> Callable[[], None]:
+        is_first = topic not in self._handlers or len(self._handlers[topic]) == 0
+        self._handlers[topic].append(handler)
+        if is_first:
+            self._send(subscribe=pb.SubscribeRequest(topic=topic))
+
+        def unsubscribe() -> None:
+            handlers = self._handlers.get(topic, [])
+            if handler in handlers:
+                handlers.remove(handler)
+            if not handlers:
+                self._send(unsubscribe=pb.UnsubscribeRequest(topic=topic))
+
+        return unsubscribe
+
+
+def create_unix_socket_context_bus(socket_path: str) -> ContextBusClient:
+    deadline = time.monotonic() + CONNECT_TIMEOUT_S
+    last_error: Optional[OSError] = None
+    while time.monotonic() < deadline:
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        try:
+            sock.connect(socket_path)
+            return ContextBusClient(sock)
+        except OSError as err:
+            last_error = err
+            sock.close()
+            time.sleep(CONNECT_RETRY_INTERVAL_S)
+    raise TimeoutError(f"timed out connecting to {socket_path} after {CONNECT_TIMEOUT_S}s: {last_error}")

berth_sdk/context_bus_pb2.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: context_bus.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'context_bus.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x11\x63ontext_bus.proto\x12\x10\x62\x65rth.contextbus\"\x1e\n\x0fRegisterRequest\x12\x0b\n\x03\x61pp\x18\x01 \x01(\t\"0\n\x0ePublishRequest\x12\r\n\x05topic\x18\x01 \x01(\t\x12\x0f\n\x07payload\x18\x02 \x01(\x0c\"!\n\x10SubscribeRequest\x12\r\n\x05topic\x18\x01 \x01(\t\"#\n\x12UnsubscribeRequest\x12\r\n\x05topic\x18\x01 \x01(\t\"\'\n\x05\x45vent\x12\r\n\x05topic\x18\x01 \x01(\t\x12\x0f\n\x07payload\x18\x02 \x01(\x0c\" \n\x03\x41\x63k\x12\n\n\x02ok\x18\x01 \x01(\x08\x12\r\n\x05\x65rror\x18\x02 \x01(\t\"\xc4\x02\n\x08\x45nvelope\x12\x35\n\x08register\x18\x01 \x01(\x0b\x32!.berth.contextbus.RegisterRequestH\x00\x12\x33\n\x07publish\x18\x02 \x01(\x0b\x32 .berth.contextbus.PublishRequestH\x00\x12\x37\n\tsubscribe\x18\x03 \x01(\x0b\x32\".berth.contextbus.SubscribeRequestH\x00\x12;\n\x0bunsubscribe\x18\x04 \x01(\x0b\x32$.berth.contextbus.UnsubscribeRequestH\x00\x12(\n\x05\x65vent\x18\x05 \x01(\x0b\x32\x17.berth.contextbus.EventH\x00\x12$\n\x03\x61\x63k\x18\x06 \x01(\x0b\x32\x15.berth.contextbus.AckH\x00\x42\x06\n\x04kindb\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'context_bus_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_REGISTERREQUEST']._serialized_start=39
+  _globals['_REGISTERREQUEST']._serialized_end=69
+  _globals['_PUBLISHREQUEST']._serialized_start=71
+  _globals['_PUBLISHREQUEST']._serialized_end=119
+  _globals['_SUBSCRIBEREQUEST']._serialized_start=121
+  _globals['_SUBSCRIBEREQUEST']._serialized_end=154
+  _globals['_UNSUBSCRIBEREQUEST']._serialized_start=156
+  _globals['_UNSUBSCRIBEREQUEST']._serialized_end=191
+  _globals['_EVENT']._serialized_start=193
+  _globals['_EVENT']._serialized_end=232
+  _globals['_ACK']._serialized_start=234
+  _globals['_ACK']._serialized_end=266
+  _globals['_ENVELOPE']._serialized_start=269
+  _globals['_ENVELOPE']._serialized_end=593
+# @@protoc_insertion_point(module_scope)

berth_sdk/generate_capability_policy.py

@@ -0,0 +1,117 @@
+"""Mirrors @berthos/sdk's generate-capability-policy.ts exactly (same policy
+shape, same deny-by-default network/opt-in read-path rules, same
+per-app baseline write/read paths) — agent-init (Rust) reads whichever
+one ran, TypeScript or Python, without caring which wrote it. Invoked as
+`python3 -m berth_sdk.generate_capability_policy`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from .manifest import load_manifest, parse_capability
+
+# Per-app, not container-wide: this used to be all of /tmp for every app, which
+# let one app reach another's RPC socket. See the TypeScript original for why a
+# narrower Landlock policy is only half the fix (DAC is the other half) and for
+# the socket layout these two directories belong to.
+#
+# /dev/null is the one entry that stays shared, and it is here rather than in
+# TERMINAL_WRITE_PATHS because opening it read-write is what any process does
+# when it redirects a child's stdio to it — see the TypeScript original for the
+# strace this came from, and for why /dev/tty is deliberately absent
+# 
+def _baseline_write_paths(app_name: str) -> list[str]:
+    return ["/dev/null", f"/tmp/{app_name}", f"/run/berth/{app_name}"]
+
+# Added only for an app declaring terminal:* — the one thing that capability
+# compiles into the kernel policy. Without it a tmux server cannot allocate a
+# pty on a Landlock-enforcing kernel.
+TERMINAL_WRITE_PATHS = ["/dev/pts", "/dev/ptmx"]
+
+# Where github-api-broker.cjs writes the CA an app declaring github:* is told
+# to trust. Read-granted only for such an app, and only because that CA moved
+# out of /tmp (which the read baseline covers in full) into /run/berth —
+# Kept in step with that script's own default.
+GITHUB_BROKER_CERT_DIR = "/run/berth/github-api-broker"
+
+
+# /tmp stays fully readable even though it is no longer fully writable: reads
+# are not what 1.4 was about, and statting a daemon control socket before
+# connecting to it needs them.
+def _baseline_read_paths(app_name: str) -> list[str]:
+    return ["/usr", "/lib", "/etc", "/proc", "/dev", "/tmp", f"/run/berth/{app_name}", str(Path.cwd())]
+
+
+def _strip_trailing_glob(scope: str) -> str:
+    return scope[:-2] if scope.endswith("/*") else scope
+
+
+
+def main() -> None:
+    manifest_path = os.environ.get("BERTH_MANIFEST_PATH", str(Path.cwd() / "berth.yml"))
+    policy_path = Path(os.environ.get("BERTH_CAPABILITY_POLICY", str(Path.cwd() / ".berth" / "capability-policy.json")))
+
+    manifest = load_manifest(manifest_path)
+    effective_capabilities = list(manifest.capabilities)
+
+    write_paths = set(_baseline_write_paths(manifest.name))
+    declared_read_paths: set[str] = set()
+    network_ports: set[int] = set()
+    network_unrestricted = False
+    needs_github_broker_ca = False
+
+    for capability in effective_capabilities:
+        parsed = parse_capability(capability)
+        if parsed.namespace == "filesystem" and parsed.action == "write":
+            write_paths.add(_strip_trailing_glob(parsed.scope))
+        elif parsed.namespace == "filesystem" and parsed.action == "read":
+            declared_read_paths.add(_strip_trailing_glob(parsed.scope))
+        elif parsed.namespace == "network" and parsed.action == "connect":
+            if parsed.scope == "*":
+                network_unrestricted = True
+                continue
+            try:
+                port = int(parsed.scope)
+            except ValueError:
+                port = -1
+            if 0 < port <= 65535:
+                network_ports.add(port)
+            else:
+                print(f'[berth:capability-policy] WARNING: ignoring invalid network:connect scope "{parsed.scope}" (expected a port 1-65535, or "*")')
+        elif parsed.namespace == "terminal":
+            write_paths.update(TERMINAL_WRITE_PATHS)
+        elif parsed.namespace == "github":
+            needs_github_broker_ca = True
+
+    baseline_reads = set(_baseline_read_paths(manifest.name))
+    if needs_github_broker_ca:
+        baseline_reads.add(GITHUB_BROKER_CERT_DIR)
+    read_paths = sorted(baseline_reads | declared_read_paths) if declared_read_paths else []
+
+    policy = {
+        "appName": manifest.name,
+        "declaredCapabilities": effective_capabilities,
+        "writePaths": sorted(write_paths),
+        "readPaths": read_paths,
+        "networkPorts": sorted(network_ports),
+        "networkUnrestricted": network_unrestricted,
+    }
+
+    policy_path.parent.mkdir(parents=True, exist_ok=True)
+    policy_path.write_text(json.dumps(policy, indent=2))
+
+    if network_unrestricted:
+        network_summary = "networkPorts=* (unrestricted)"
+    elif network_ports:
+        network_summary = f"networkPorts={', '.join(str(p) for p in sorted(network_ports))}"
+    else:
+        network_summary = "networkPorts=(none — network denied by default)"
+    read_summary = f"; readPaths={', '.join(read_paths)}" if read_paths else ""
+    print(f"[berth:capability-policy] wrote {policy_path}: writePaths={', '.join(sorted(write_paths))}{read_summary}; {network_summary}")
+
+
+if __name__ == "__main__":
+    main()

berth_sdk/local_context_bus.py

@@ -0,0 +1,36 @@
+"""Mirrors @berthos/sdk's context-bus/local.ts — an in-process no-op fallback
+used when the real Unix-socket daemon isn't reachable (e.g. running an app
+outside a sandbox during a quick script/test)."""
+
+from __future__ import annotations
+
+import logging
+from collections import defaultdict
+from typing import Any, Callable
+
+logger = logging.getLogger("berth.context_bus.local")
+
+
+class LocalContextBus:
+    def __init__(self) -> None:
+        self._handlers: dict[str, list[Callable[[Any], None]]] = defaultdict(list)
+
+    # Plain synchronous methods — see context_bus.py's own comment on why
+    # these deliberately aren't `async def` in this runtime.
+    def register(self, app: str) -> None:
+        logger.debug('register app="%s" (no-op — real daemon not connected)', app)
+
+    def publish(self, topic: str, payload: Any) -> None:
+        logger.debug('publish topic="%s"', topic)
+        for handler in list(self._handlers.get(topic, [])):
+            handler(payload)
+
+    def subscribe(self, topic: str, handler: Callable[[Any], None]) -> Callable[[], None]:
+        logger.debug('subscribe topic="%s"', topic)
+        self._handlers[topic].append(handler)
+
+        def unsubscribe() -> None:
+            if handler in self._handlers[topic]:
+                self._handlers[topic].remove(handler)
+
+        return unsubscribe

berth_sdk/manifest.py

@@ -0,0 +1,93 @@
+"""Mirrors @berthos/manifest-schema's schema.ts/capability.ts — the manifest
+shape and capability-string grammar are plain data (YAML + a
+namespace:action:scope string), not TypeScript-specific, so a Python
+implementation validates the exact same shape rather than porting any code.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, Field, field_validator
+
+CAPABILITY_RE = re.compile(r"^[a-z0-9_-]+:[a-z0-9_-]+:.+$")
+NAME_RE = re.compile(r"^[a-z0-9-]+$")
+VERSION_RE = re.compile(r"^\d+\.\d+\.\d+$")
+
+JsonPrimitiveType = Literal["string", "number", "boolean", "object", "array"]
+
+
+class ExportSpec(BaseModel):
+    name: str
+    input: dict[str, JsonPrimitiveType] = Field(default_factory=dict)
+    output: dict[str, JsonPrimitiveType] = Field(default_factory=dict)
+
+
+class BerthManifest(BaseModel):
+    name: str
+    version: str
+    description: str = ""
+    capabilities: list[str] = Field(default_factory=list)
+    exports: list[ExportSpec] = Field(default_factory=list)
+    on_install: list[str] = Field(default_factory=list)
+    on_agent_ready: list[str] = Field(default_factory=list)
+
+    @field_validator("name")
+    @classmethod
+    def _validate_name(cls, v: str) -> str:
+        if not NAME_RE.match(v):
+            raise ValueError("name must be lowercase alphanumeric with dashes")
+        return v
+
+    @field_validator("version")
+    @classmethod
+    def _validate_version(cls, v: str) -> str:
+        if not VERSION_RE.match(v):
+            raise ValueError("version must be semver (x.y.z)")
+        return v
+
+    @field_validator("capabilities")
+    @classmethod
+    def _validate_capabilities(cls, v: list[str]) -> list[str]:
+        for cap in v:
+            if not CAPABILITY_RE.match(cap):
+                raise ValueError(f"capability must be 'namespace:action:scope', got {cap!r}")
+        return v
+
+
+def load_manifest(path: str) -> BerthManifest:
+    with open(path, "r", encoding="utf-8") as f:
+        raw = yaml.safe_load(f) or {}
+    return BerthManifest.model_validate(raw)
+
+
+class ParsedCapability:
+    __slots__ = ("namespace", "action", "scope")
+
+    def __init__(self, namespace: str, action: str, scope: str) -> None:
+        self.namespace = namespace
+        self.action = action
+        self.scope = scope
+
+
+def parse_capability(capability: str) -> ParsedCapability:
+    parts = capability.split(":")
+    if len(parts) < 3:
+        raise ValueError(f'invalid capability string "{capability}": expected \'namespace:action:scope\'')
+    namespace, action, *scope_parts = parts
+    return ParsedCapability(namespace, action, ":".join(scope_parts))
+
+
+def _glob_to_regex(glob: str) -> re.Pattern[str]:
+    escaped = re.escape(glob).replace(r"\*", ".*")
+    return re.compile(f"^{escaped}$")
+
+
+def matches_capability(granted: str, requested: str) -> bool:
+    g = parse_capability(granted)
+    r = parse_capability(requested)
+    if g.namespace != r.namespace or g.action != r.action:
+        return False
+    return bool(_glob_to_regex(g.scope).match(r.scope))

berth_sdk/rpc.py

@@ -0,0 +1,108 @@
+"""The identical line-delimited JSON RPC protocol from @berthos/sdk's rpc.ts —
+{id, export, input} in, {id, result} or {id, error} out — over stdio and,
+optionally, a Unix socket. No length-prefix, no protobuf: this is the
+simplest of the two wire protocols this SDK reuses (see context_bus.py for
+the other, protobuf-framed one), so a straight re-implementation rather than
+anything requiring codegen.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socketserver
+import sys
+import threading
+from typing import Any, Callable, Optional
+
+from .app import BerthApp
+
+RpcRequest = dict[str, Any]
+RpcResponse = dict[str, Any]
+
+
+def invoke_export(app: BerthApp, request: RpcRequest) -> RpcResponse:
+    export_def = app.exports.get(request.get("export"))
+    if export_def is None:
+        return {"id": request.get("id"), "error": f'no such export "{request.get("export")}"'}
+
+    try:
+        raw_input = request.get("input")
+        parsed_input = export_def.input_model.model_validate(raw_input) if export_def.input_model else raw_input
+        result = export_def.handler(parsed_input)
+
+        if export_def.output_model is not None and not isinstance(result, export_def.output_model):
+            result = export_def.output_model.model_validate(result)
+        output_payload = result.model_dump() if hasattr(result, "model_dump") else result
+
+        return {"id": request.get("id"), "result": output_payload}
+    except Exception as err:  # matches rpc.ts's catch-all — reported back to the caller, not raised
+        return {"id": request.get("id"), "error": str(err)}
+
+
+def _handle_line(app: BerthApp, line: str, write: Callable[[str], None]) -> None:
+    line = line.strip()
+    if not line:
+        return
+    try:
+        request = json.loads(line)
+    except json.JSONDecodeError:
+        print(f"[berth:runtime] ignoring non-JSON RPC line: {line}", file=sys.stderr)
+        return
+    response = invoke_export(app, request)
+    write(json.dumps(response))
+
+
+class _RpcSocketHandler(socketserver.StreamRequestHandler):
+    def handle(self) -> None:
+        app: BerthApp = self.server.app  # type: ignore[attr-defined]
+
+        def write(resp: str) -> None:
+            self.wfile.write((resp + "\n").encode("utf-8"))
+            self.wfile.flush()
+
+        while True:
+            raw = self.rfile.readline()
+            if not raw:
+                break
+            line = raw.decode("utf-8")
+            if not line.strip():
+                continue
+            _handle_line(app, line, write)
+
+
+class _RpcUnixStreamServer(socketserver.ThreadingUnixStreamServer):
+    daemon_threads = True
+
+
+def start_socket_server(app: BerthApp, socket_path: str) -> None:
+    try:
+        os.unlink(socket_path)
+    except FileNotFoundError:
+        pass
+
+    server = _RpcUnixStreamServer(socket_path, _RpcSocketHandler)
+    server.app = app  # type: ignore[attr-defined]
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    print(f"[berth:runtime] RPC server also listening on {socket_path}", file=sys.stderr)
+
+
+def start_rpc_server(app: BerthApp, socket_path: Optional[str] = None) -> None:
+    """Starts the (optional) socket server and logs readiness — does NOT
+    block. serve_stdio_forever() is the blocking call, run last in
+    runtime.py's boot sequence so "ready" logs before it, matching rpc.ts's
+    ordering (its own startRpcServer() is non-blocking; Node's event loop
+    is what keeps the process alive)."""
+    print("[berth:runtime] RPC server listening on stdio", file=sys.stderr)
+    if socket_path:
+        start_socket_server(app, socket_path)
+
+
+def serve_stdio_forever(app: BerthApp) -> None:
+    def write(resp: str) -> None:
+        sys.stdout.write(resp + "\n")
+        sys.stdout.flush()
+
+    for line in sys.stdin:
+        _handle_line(app, line, write)

berth_sdk/run_lifecycle.py

@@ -0,0 +1,37 @@
+"""Mirrors @berthos/sdk's run-lifecycle.ts: reports whether a browser:*
+capability is declared, and separately whether a browser:navigate:*/
+network:host:* capability is declared (entrypoint.sh's own trigger for
+starting the egress broker), via the last stdout line ("1,1" / "0,1" / etc.)
+— entrypoint.sh's Python branch parses this exactly like it already does for
+the Node lifecycle script.
+
+It used to also execute the manifest's on_install commands, once, tracked by
+a marker file. That ran as uid 0 with no Landlock domain applied, before one
+could exist; on_install is now a Docker build layer for
+both build targets, and nothing runs it at container boot. See the fuller
+note in run-lifecycle.ts. The marker file went with it — there is no longer a
+boot-time action to run at most once.
+
+Invoked as `python3 -m berth_sdk.run_lifecycle`.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .manifest import load_manifest
+
+
+def main() -> None:
+    manifest_path = os.environ.get("BERTH_MANIFEST_PATH", str(Path.cwd() / "berth.yml"))
+
+    manifest = load_manifest(manifest_path)
+
+    needs_browser = any(cap.startswith("browser:") for cap in manifest.capabilities)
+    needs_egress_broker = any(cap.startswith("browser:navigate:") or cap.startswith("network:host:") for cap in manifest.capabilities)
+    print(f"{'1' if needs_browser else '0'},{'1' if needs_egress_broker else '0'}")
+
+
+if __name__ == "__main__":
+    main()

berth_sdk/runtime.py

@@ -0,0 +1,94 @@
+"""Mirrors @berthos/sdk's runtime.ts boot sequence: load manifest -> import the
+app module -> assert exports match manifest -> run hooks -> serve RPC. The
+orchestration itself is idiomatic Python (importlib, not a port of Node's
+dynamic import()) — only the wire protocols (manifest shape, RPC framing)
+are shared with the TypeScript SDK, not this glue code.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import sys
+from pathlib import Path
+
+from .app import AppContext, BerthApp
+from .context_bus import create_unix_socket_context_bus
+from .local_context_bus import LocalContextBus
+from .manifest import load_manifest
+from .rpc import serve_stdio_forever, start_rpc_server
+
+
+def _create_context_bus():
+    """Real context-bus daemon if reachable (entrypoint.sh starts it before
+    this runtime — same file/env contract @berthos/sdk's runtime.ts uses);
+    falls back to a local no-op otherwise, so an app never hard-fails just
+    because it's running outside a sandbox with the daemon (e.g. a bare
+    `python3 -m berth_sdk.runtime` during a quick script)."""
+    socket_path = os.environ.get("BERTH_CONTEXT_BUS_SOCKET", "/tmp/berth-context-bus.sock")
+    try:
+        return create_unix_socket_context_bus(socket_path)
+    except Exception as err:  # noqa: BLE001 - genuinely any connection failure should fall back, not crash boot
+        print(
+            f"[berth:runtime] context-bus daemon not reachable at {socket_path} ({err}) — falling back to local no-op",
+            file=sys.stderr,
+        )
+        return LocalContextBus()
+
+
+def _assert_exports_match_manifest(app: BerthApp, declared_exports: list[str]) -> None:
+    code_exports = set(app.exports.keys())
+    manifest_exports = set(declared_exports)
+
+    missing_in_code = sorted(manifest_exports - code_exports)
+    missing_in_manifest = sorted(code_exports - manifest_exports)
+
+    if missing_in_code or missing_in_manifest:
+        problems = []
+        if missing_in_code:
+            problems.append(f"declared in berth.yml but not implemented: {', '.join(missing_in_code)}")
+        if missing_in_manifest:
+            problems.append(f"implemented in code but not declared in berth.yml: {', '.join(missing_in_manifest)}")
+        raise RuntimeError(f"exports mismatch between berth.yml and app code — {'; '.join(problems)}")
+
+
+def main() -> None:
+    app_root = Path(os.getcwd())
+    manifest_path = os.environ.get("BERTH_MANIFEST_PATH", str(app_root / "berth.yml"))
+    app_entry = os.environ.get("BERTH_APP_ENTRY", str(app_root / "src" / "app.py"))
+
+    print(f"[berth:runtime] loading manifest from {manifest_path}", file=sys.stderr)
+    manifest = load_manifest(manifest_path)
+
+    print(f"[berth:runtime] loading app entry {app_entry}", file=sys.stderr)
+    spec = importlib.util.spec_from_file_location("berth_app_entry", app_entry)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"could not load a Python module from {app_entry}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    app = getattr(module, "app", None)
+    if not isinstance(app, BerthApp):
+        raise RuntimeError(f"{app_entry} must define a module-level `app = define_app(...)`")
+
+    _assert_exports_match_manifest(app, [e.name for e in manifest.exports])
+
+    for hook in app.on_install_hooks:
+        hook()
+
+    context_bus = _create_context_bus()
+    ctx = AppContext(manifest, context_bus)
+    for hook in app.on_agent_ready_hooks:
+        hook(ctx)
+
+    start_rpc_server(app, socket_path=os.environ.get("BERTH_RPC_SOCKET"))
+    print(f'[berth:runtime] "{manifest.name}" ready', file=sys.stderr)
+
+    # Blocks forever, reading stdio RPC requests — this is what keeps the
+    # process alive, same role Node's active readline listener plays in
+    # rpc.ts (its event loop just never empties).
+    serve_stdio_forever(app)
+
+
+if __name__ == "__main__":
+    main()

berthos_sdk-0.2.1.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: berthos-sdk
+Version: 0.2.1
+Summary: Python resident-app SDK for Berth — reuses the same wire protocols as @berthos/sdk (RPC newline-JSON framing, the manifest shape), with idiomatic Python runtime glue rather than a port of the TypeScript code.
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: protobuf>=6.30
+Dynamic: license-file
+
+# berthos-sdk
+
+Build a Berth resident app in Python. It uses the same `berth.yml` manifest, RPC protocol and context bus as the TypeScript SDK, `@berthos/sdk`.
+
+[Berth](https://github.com/Ash20pk/BerthOS) runs an AI agent's tools in a sandbox. Each tool declares what it may touch in a `berth.yml` manifest, and the Linux kernel enforces it.
+
+```sh
+pip install berthos-sdk
+```
+
+Needs Python 3.11+. The import name is `berth_sdk`.
+
+## Usage
+
+```python
+from berth_sdk import define_app
+from pydantic import BaseModel
+
+
+class GreetInput(BaseModel):
+    name: str
+
+
+class GreetOutput(BaseModel):
+    message: str
+
+
+def setup(app):
+    app.export(
+        "greet",
+        lambda inp: GreetOutput(message=f"hello {inp.name}"),
+        input_model=GreetInput,
+        output_model=GreetOutput,
+    )
+
+
+app = define_app(setup)
+```
+
+Declare `greet` under `exports` in `berth.yml` too. Without `input_model`, a handler receives the raw input dict. Run the app with `berth dev` from [`@berthos/cli`](https://www.npmjs.com/package/@berthos/cli); the [`hello-world-py`](https://github.com/Ash20pk/BerthOS/tree/main/apps/hello-world-py) app is a complete example.
+
+## Docs
+
+[Python SDK reference](https://github.com/Ash20pk/BerthOS/blob/main/docs/sdk-python-reference.md) · [Python and the context bus](https://github.com/Ash20pk/BerthOS/blob/main/docs/sdk-python-context-bus-reference.md) · [Repo](https://github.com/Ash20pk/BerthOS)

berthos_sdk-0.2.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+berth_sdk/__init__.py,sha256=tI0S0C0EfRSaKn9QSWSMAuCruGThSsk6nCV_EvPTetY,328
+berth_sdk/app.py,sha256=VByQwnbsoTSJYGmt5Bik9nqS7BkvMz-MKRFPAB0Nep4,2251
+berth_sdk/context_bus.py,sha256=rx6btr9vwNRD_VbNa-xmReEv2h9IQusxiZiYi5GRw_8,4713
+berth_sdk/context_bus_pb2.py,sha256=L-r3ITTpSH6me9OKIbDe0P8OjBftQZPq9e1nrVxAh0s,2798
+berth_sdk/generate_capability_policy.py,sha256=aXPWoG80lV8tWx79bZPNFw5_UWOeshxtKidnmCug9Rg,5075
+berth_sdk/local_context_bus.py,sha256=IwOsteW9vzKuHiiKMKX4JY7nFxstYaBK6NePrEBkayU,1340
+berth_sdk/manifest.py,sha256=Dy6gUS7pfOhy0VRJnusofoum8OsUUJUofkrfcqDFhFc,3066
+berth_sdk/rpc.py,sha256=jq-dVPz5cjeqYourUxqneLfyeqewZUNAzVpobmvBX5k,3851
+berth_sdk/run_lifecycle.py,sha256=L5EL_1oA1epSVAGQAtPeTX-K9X53rSKajQ2s2Bhmz4M,1462
+berth_sdk/runtime.py,sha256=aXNabghZbv35qkOnoUcc90wfMMwSJr0G5z0crfTwX58,3924
+berthos_sdk-0.2.1.dist-info/licenses/LICENSE,sha256=GBf0DItgJwnSPuTQIRW-LWf9Qy_5TYJNY2lPSYFdXBM,6264
+berthos_sdk-0.2.1.dist-info/METADATA,sha256=kuyDkDaZ0JnMyueSGlhq2VmK9dqJsV6zpq8_z35Iat4,1925
+berthos_sdk-0.2.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+berthos_sdk-0.2.1.dist-info/top_level.txt,sha256=qlYc7VHzBbl7mwViEObDLpeuGPz4X73M84Oa69VflKI,10
+berthos_sdk-0.2.1.dist-info/RECORD,,

berthos_sdk-0.2.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

berthos_sdk-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,121 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions: (a) You must give any other
+      recipients of the Work or Derivative Works a copy of this License;
+      (b) You must cause any modified files to carry prominent notices
+      stating that You changed the files; (c) You must retain, in the
+      Source form of any Derivative Works that You distribute, all
+      copyright, patent, trademark, and attribution notices from the
+      Source form of the Work; (d) If the Work includes a "NOTICE" text
+      file, any Derivative Works You distribute must include a readable
+      copy of the attribution notices contained within such NOTICE file.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort, negligence, contract, or otherwise, shall any
+      Contributor be liable to You for damages, including any direct,
+      indirect, special, incidental, or consequential damages arising
+      as a result of this License or out of the use or inability to use
+      the Work.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations consistent with this License.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Berth Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

berthos_sdk-0.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+berth_sdk