bazaar-compute-node 0.1.3__py3-none-any.whl

bazaar_compute_node/contrib/wecom/markdown.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class _Fence:
+    marker: str
+    opening: str
+
+
+def split_markdown(content: str, *, limit: int) -> tuple[str, ...]:
+    if limit <= 0:
+        raise ValueError("limit must be positive")
+    if not content:
+        return (content,)
+
+    chunks: list[str] = []
+    cursor = 0
+    fence: _Fence | None = None
+    while cursor < len(content):
+        prefix = f"{fence.opening}\n" if fence is not None else ""
+        prefix_bytes = len(prefix.encode("utf-8"))
+        end = cursor
+        size = prefix_bytes
+        while end < len(content):
+            encoded = content[end].encode("utf-8")
+            if size + len(encoded) > limit:
+                break
+            size += len(encoded)
+            end += 1
+        if end == cursor:
+            raise ValueError("markdown fence overhead exceeds the provider byte limit")
+
+        while True:
+            next_fence = _advance_fence(
+                fence,
+                content[cursor:end],
+                initial_line_boundary=(cursor == 0 or content[cursor - 1] in "\r\n"),
+                terminal_line_complete=(end == len(content) or content[end] in "\r\n"),
+            )
+            suffix = _closing_suffix(prefix + content[cursor:end], next_fence)
+            if len((prefix + content[cursor:end] + suffix).encode("utf-8")) <= limit:
+                break
+            end -= 1
+            if end == cursor:
+                raise ValueError(
+                    "markdown fence closure exceeds the provider byte limit"
+                )
+
+        if end < len(content):
+            minimum = cursor + max(1, (end - cursor) // 2)
+            preferred = _preferred_boundary(content, cursor, end, minimum)
+            if preferred is not None:
+                preferred_fence = _advance_fence(
+                    fence,
+                    content[cursor:preferred],
+                    initial_line_boundary=(
+                        cursor == 0 or content[cursor - 1] in "\r\n"
+                    ),
+                    terminal_line_complete=(
+                        preferred == len(content) or content[preferred] in "\r\n"
+                    ),
+                )
+                preferred_suffix = _closing_suffix(
+                    prefix + content[cursor:preferred], preferred_fence
+                )
+                if (
+                    len(
+                        (prefix + content[cursor:preferred] + preferred_suffix).encode(
+                            "utf-8"
+                        )
+                    )
+                    <= limit
+                ):
+                    end = preferred
+                    next_fence = preferred_fence
+                    suffix = preferred_suffix
+
+        chunks.append(prefix + content[cursor:end] + suffix)
+        cursor = end
+        fence = next_fence
+
+    return tuple(chunks)
+
+
+def _preferred_boundary(
+    content: str, cursor: int, end: int, minimum: int
+) -> int | None:
+    for separator in ("\n\n", "\n"):
+        index = content.rfind(separator, minimum, end)
+        if index >= minimum:
+            return index + len(separator)
+    for index in range(end - 1, minimum - 1, -1):
+        if content[index].isspace():
+            return index + 1
+    return None
+
+
+def _advance_fence(
+    fence: _Fence | None,
+    segment: str,
+    *,
+    initial_line_boundary: bool,
+    terminal_line_complete: bool,
+) -> _Fence | None:
+    lines = segment.splitlines(keepends=True)
+    for index, line in enumerate(lines):
+        complete = (index > 0 or initial_line_boundary) and (
+            line.endswith(("\n", "\r"))
+            or (index == len(lines) - 1 and terminal_line_complete)
+        )
+        if not complete:
+            continue
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if fence is None:
+            marker_char = stripped[0]
+            if marker_char not in {"`", "~"}:
+                continue
+            marker_length = len(stripped) - len(stripped.lstrip(marker_char))
+            if marker_length < 3:
+                continue
+            marker = marker_char * marker_length
+            info = stripped[marker_length:]
+            if marker_char == "`" and "`" in info:
+                continue
+            fence = _Fence(marker=marker, opening=stripped)
+            continue
+        if stripped[0] != fence.marker[0]:
+            continue
+        marker_length = len(stripped) - len(stripped.lstrip(fence.marker[0]))
+        if marker_length >= len(fence.marker) and not stripped[marker_length:].strip():
+            fence = None
+    return fence
+
+
+def _closing_suffix(content: str, fence: _Fence | None) -> str:
+    if fence is None:
+        return ""
+    separator = "" if content.endswith(("\n", "\r")) else "\n"
+    return f"{separator}{fence.marker}"
+
+
+__all__ = ["split_markdown"]

bazaar_compute_node/contrib/wecom/plugin.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import os
+
+from ...core.channel import ChannelContext, IChannel
+from .channel import WeComChannel
+
+
+def create_channel(context: ChannelContext) -> IChannel:
+    bot_id = context.options.get("bot_id")
+    websocket_url = context.options.get("websocket_url")
+    if not isinstance(bot_id, str) or not bot_id:
+        raise ValueError("channel.wecom.bot_id is required")
+    if websocket_url is not None and (
+        not isinstance(websocket_url, str) or not websocket_url
+    ):
+        raise ValueError("channel.wecom.websocket_url must be non-empty text")
+    secret = os.environ.get("BCN_WECOM_BOT_SECRET")
+    if not secret:
+        raise ValueError("BCN_WECOM_BOT_SECRET is required")
+    return WeComChannel(
+        context,
+        bot_id=bot_id,
+        secret=secret,
+        websocket_url=websocket_url or "wss://openws.work.weixin.qq.com",
+    )
+
+
+__all__ = ["create_channel"]

bazaar_compute_node/core/__init__.py

@@ -0,0 +1,5 @@
+"""Provider-neutral application contracts and domain models."""
+
+from .client import CLIENT_INFO, CLIENT_NAME, CLIENT_VERSION, ClientInfo
+
+__all__ = ["CLIENT_INFO", "CLIENT_NAME", "CLIENT_VERSION", "ClientInfo"]

bazaar_compute_node/core/approval.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from .models import ApprovalRequest, ApprovalResult
+
+
+class IApprovalHandler(Protocol):
+    """Neutral callback used by a runtime adapter for approval requests."""
+
+    async def request_approval(
+        self, request: ApprovalRequest, *, timeout: float
+    ) -> ApprovalResult:
+        """Route one request to the current Channel approval policy."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class ApprovalBinding:
+    """Route one runtime approval request to its current Channel session."""
+
+    request_id: str
+    bcn_session_id: str
+    channel_session_id: str
+    runtime_session_id: str
+    turn_id: str | None = None
+
+    def __post_init__(self) -> None:
+        for value, field_name in (
+            (self.request_id, "request_id"),
+            (self.bcn_session_id, "bcn_session_id"),
+            (self.channel_session_id, "channel_session_id"),
+            (self.runtime_session_id, "runtime_session_id"),
+        ):
+            if not isinstance(value, str) or not value:
+                raise ValueError(f"{field_name} must be a non-empty string")
+        if self.turn_id is not None and (
+            not isinstance(self.turn_id, str) or not self.turn_id
+        ):
+            raise ValueError("turn_id must be a non-empty string when present")
+
+    def matches(self, request: ApprovalRequest) -> bool:
+        """Ensure a response is returned to the same runtime request context."""
+
+        return (
+            self.request_id == request.request_id
+            and self.bcn_session_id == request.session_id
+            and self.runtime_session_id == request.runtime_session_id
+            and self.turn_id == request.turn_id
+        )

bazaar_compute_node/core/audit.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from .correlation import CorrelationContext
+from .models import RuntimeEventState
+from .observability import LogLevel
+
+
+class ErrorKind(StrEnum):
+    CANCELLED = "cancelled"
+    TIMEOUT = "timeout"
+    VALIDATION = "validation"
+    SESSION_NOT_FOUND = "session_not_found"
+    TARGET_NOT_REPLYABLE = "target_not_replyable"
+    EMPTY_BODY = "empty_body"
+    FRESH_CHECK_REQUIRED = "fresh_check_required"
+    FRESH_CHECK_FAILED = "fresh_check_failed"
+    PROVIDER_FAILED = "provider_failed"
+    PROVIDER_PARTIAL = "provider_partial"
+    PROVIDER_UNKNOWN = "provider_unknown"
+    PROTOCOL = "protocol"
+    STORAGE = "storage"
+    SHUTDOWN_TIMEOUT = "shutdown_timeout"
+    INTERNAL = "internal"
+
+
+_FORBIDDEN_METADATA_KEYS = frozenset(
+    {
+        "access_token",
+        "api_key",
+        "authorization",
+        "body",
+        "cookie",
+        "credential",
+        "payload",
+        "raw_payload",
+        "secret",
+        "token",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class AuditEvent:
+    """Sanitized append-only event contract shared by all adapters."""
+
+    event_name: str
+    state: RuntimeEventState
+    created_at_ms: int
+    correlation: CorrelationContext
+    level: LogLevel = LogLevel.INFO
+    duration_ms: int | None = None
+    error_kind: ErrorKind | None = None
+    error_type: str | None = None
+    error_message: str | None = None
+    traceback_ref: str | None = None
+    metadata: Mapping[str, object] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.event_name, str) or not self.event_name:
+            raise ValueError("event_name must be a non-empty string")
+        if (
+            isinstance(self.created_at_ms, bool)
+            or not isinstance(self.created_at_ms, int)
+            or self.created_at_ms < 0
+        ):
+            raise ValueError("created_at_ms must be a non-negative integer")
+        if self.duration_ms is not None and (
+            isinstance(self.duration_ms, bool)
+            or not isinstance(self.duration_ms, int)
+            or self.duration_ms < 0
+        ):
+            raise ValueError("duration_ms must be a non-negative integer when present")
+        if self.error_kind is None and any(
+            value is not None
+            for value in (
+                self.error_type,
+                self.error_message,
+                self.traceback_ref,
+            )
+        ):
+            raise ValueError("error details require an error_kind")
+        for value, field_name in (
+            (self.error_type, "error_type"),
+            (self.error_message, "error_message"),
+            (self.traceback_ref, "traceback_ref"),
+        ):
+            if value is not None and (not isinstance(value, str) or not value):
+                raise ValueError(
+                    f"{field_name} must be a non-empty string when present"
+                )
+        for key in self.metadata:
+            if not isinstance(key, str):
+                raise TypeError("audit metadata keys must be strings")
+            if key.casefold() in _FORBIDDEN_METADATA_KEYS:
+                raise ValueError(
+                    f"audit metadata cannot contain sensitive field: {key}"
+                )

bazaar_compute_node/core/channel.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterable, AsyncIterator, Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from .approval import IApprovalHandler
+from .lifecycle import IAsyncLifecycle
+from .models import (
+    ChannelTargetKind,
+    InboundAttachment,
+    InboundMessage,
+    OutboundMessage,
+    StreamEvent,
+)
+from .outcomes import ProviderCallResult
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelDeliveryReceipt:
+    """Provider receipt fields safe for the core delivery audit."""
+
+    provider_message_id: str | None = None
+    provider_receipt_ref: str | None = None
+
+    def __post_init__(self) -> None:
+        for value, field_name in (
+            (self.provider_message_id, "provider_message_id"),
+            (self.provider_receipt_ref, "provider_receipt_ref"),
+        ):
+            if value is not None and (not isinstance(value, str) or not value):
+                raise ValueError(
+                    f"{field_name} must be a non-empty string when present"
+                )
+        if self.provider_message_id is None and self.provider_receipt_ref is None:
+            raise ValueError(
+                "a channel delivery receipt requires a provider identifier"
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelSendRequest:
+    """Transient provider mapping resolved behind the runtime command boundary."""
+
+    outbound: OutboundMessage
+    target_kind: ChannelTargetKind
+    provider_thread_id: str
+    provider_reply_to_message_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.provider_thread_id:
+            raise ValueError("provider_thread_id must be non-empty")
+        if (
+            self.provider_reply_to_message_id is not None
+            and not self.provider_reply_to_message_id
+        ):
+            raise ValueError("provider_reply_to_message_id must be non-empty")
+
+
+class IAttachmentMaterializer(Protocol):
+    async def materialize(
+        self,
+        source: bytes | AsyncIterable[bytes],
+        *,
+        name: str,
+        kind: str,
+        media_type: str | None = None,
+    ) -> InboundAttachment:
+        """Persist one bounded plaintext attachment in the shared workspace."""
+        ...
+
+    def failed(
+        self,
+        *,
+        name: str,
+        kind: str,
+        error: str,
+        media_type: str | None = None,
+    ) -> InboundAttachment:
+        """Create a terminal descriptor without exposing provider references."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelContext:
+    attachments: IAttachmentMaterializer
+    options: Mapping[str, object]
+    workspace: Callable[[], Path]
+
+
+class IApproval(IApprovalHandler, Protocol):
+    """Channel-owned approval policy for one bcn session."""
+
+
+class IChannel(IAsyncLifecycle, IApproval, Protocol):
+    """Normalized inbound, outbound delivery, and approval contract."""
+
+    @property
+    def name(self) -> str:
+        """Return the stable entry-point identity of this adapter."""
+        ...
+
+    @property
+    def health(self) -> Mapping[str, object]:
+        """Return non-sensitive lifecycle and ingress capability details."""
+        ...
+
+    def receive(self) -> AsyncIterator[InboundMessage]:
+        """Return a cancellable stream of normalized inbound messages."""
+        ...
+
+    def offer_stream_event(self, event: StreamEvent) -> None:
+        """Offer one transient event without waiting for channel delivery."""
+        ...
+
+    async def send(
+        self, request: ChannelSendRequest, *, timeout: float
+    ) -> ProviderCallResult[ChannelDeliveryReceipt]:
+        """Deliver one outbound message without hiding unknown provider status."""
+        ...

bazaar_compute_node/core/client.py

@@ -0,0 +1,30 @@
+"""Provider-neutral identity for the bcn client."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .. import __version__
+
+
+@dataclass(frozen=True, slots=True)
+class ClientInfo:
+    """Canonical client identity exposed to provider protocol adapters."""
+
+    name: str
+    version: str
+
+    def __post_init__(self) -> None:
+        for field_name, value in (("name", self.name), ("version", self.version)):
+            if not isinstance(value, str) or not value:
+                raise ValueError(f"{field_name} must be a non-empty string")
+            if "\r" in value or "\n" in value:
+                raise ValueError(f"{field_name} must not contain line breaks")
+
+
+CLIENT_NAME = "bcn"
+CLIENT_VERSION = __version__
+CLIENT_INFO = ClientInfo(name=CLIENT_NAME, version=CLIENT_VERSION)
+
+
+__all__ = ["CLIENT_INFO", "CLIENT_NAME", "CLIENT_VERSION", "ClientInfo"]

bazaar_compute_node/core/command.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from .models import InboundMessage, OutboundMessage
+
+
+@dataclass(frozen=True, slots=True)
+class MessageCheckResult:
+    """Drain result with a snapshot independent from the delivery cursor."""
+
+    messages: tuple[InboundMessage, ...]
+    snapshot_seq: int
+    delivered_through_seq: int
+    referenced_messages: tuple[InboundMessage, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.snapshot_seq < 0 or self.delivered_through_seq < 0:
+            raise ValueError("message sequence values must be non-negative")
+        if self.delivered_through_seq > self.snapshot_seq:
+            raise ValueError("delivered_through_seq cannot exceed snapshot_seq")
+
+
+@dataclass(frozen=True, slots=True)
+class MessageReadResult:
+    """Non-draining history result with the observed inbox snapshot."""
+
+    messages: tuple[InboundMessage, ...]
+    snapshot_seq: int
+    first_seq: int | None = None
+    last_seq: int | None = None
+    referenced_messages: tuple[InboundMessage, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.snapshot_seq < 0:
+            raise ValueError("snapshot_seq must be non-negative")
+        if (self.first_seq is None) != (self.last_seq is None):
+            raise ValueError("first_seq and last_seq must be provided together")
+        if (
+            self.first_seq is not None
+            and self.last_seq is not None
+            and (self.first_seq < 0 or self.last_seq < self.first_seq)
+        ):
+            raise ValueError("history sequence bounds are invalid")
+
+
+class SessionNotFoundError(ValueError):
+    """A command referenced a bcn session that is not persisted on this node."""
+
+
+class ICommandService(Protocol):
+    """Session-scoped command surface used by the local wrapper."""
+
+    async def check(self, session_id: str) -> MessageCheckResult:
+        """Read new messages and advance only the delivery cursor."""
+        ...
+
+    async def read(
+        self,
+        session_id: str,
+        *,
+        target: str,
+        around_message_id: str | None = None,
+        limit: int = 100,
+    ) -> MessageReadResult:
+        """Read history without advancing the delivery cursor."""
+        ...
+
+    async def send(
+        self,
+        *,
+        session_id: str,
+        command_id: str,
+        target: str,
+        body: str,
+        created_at_ms: int,
+        reply_to_message_id: str | None = None,
+    ) -> OutboundMessage:
+        """Run the session fresh-check before calling the Channel port."""
+        ...
+
+    async def unfollow(self, session_id: str, *, target: str) -> bool:
+        """Disable future group notifications and report whether state changed."""
+        ...

bazaar_compute_node/core/concurrency.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Protocol
+
+
+class ISessionConcurrency(Protocol):
+    """Return the shared lock for one bcn session.
+
+    Command, cursor, turn, and outbound fresh-check operations for the same
+    session must use the same lock. Locks for different sessions are
+    independent and must not be acquired by a global node lock.
+    """
+
+    def for_session(self, session_id: str) -> asyncio.Lock:
+        """Return a stable lock keyed by the opaque bcn session id."""
+        ...
+
+
+class SessionLockRegistry:
+    """In-memory per-session lock registry for one running node process."""
+
+    def __init__(self) -> None:
+        self._locks: dict[str, asyncio.Lock] = {}
+
+    def for_session(self, session_id: str) -> asyncio.Lock:
+        if not isinstance(session_id, str) or not session_id:
+            raise ValueError("session_id must be a non-empty string")
+        return self._locks.setdefault(session_id, asyncio.Lock())

bazaar_compute_node/core/correlation.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class CorrelationContext:
+    """Provider-neutral identifiers shared by runtime, channel, and command flows."""
+
+    node_id: str | None = None
+    channel: str | None = None
+    channel_session_id: str | None = None
+    bcn_session_id: str | None = None
+    runtime_session_id: str | None = None
+    turn_id: str | None = None
+    request_id: str | None = None
+    command_id: str | None = None
+    inbound_seq: int | None = None
+    outbound_message_id: str | None = None
+    provider_request_id: str | None = None
+    provider_thread_id: str | None = None
+    provider_turn_id: str | None = None
+
+    def __post_init__(self) -> None:
+        for value, field_name in (
+            (self.node_id, "node_id"),
+            (self.channel, "channel"),
+            (self.channel_session_id, "channel_session_id"),
+            (self.bcn_session_id, "bcn_session_id"),
+            (self.runtime_session_id, "runtime_session_id"),
+            (self.turn_id, "turn_id"),
+            (self.request_id, "request_id"),
+            (self.command_id, "command_id"),
+            (self.outbound_message_id, "outbound_message_id"),
+            (self.provider_request_id, "provider_request_id"),
+            (self.provider_thread_id, "provider_thread_id"),
+            (self.provider_turn_id, "provider_turn_id"),
+        ):
+            if value is not None and (not isinstance(value, str) or not value):
+                raise ValueError(
+                    f"{field_name} must be a non-empty string when present"
+                )
+        if self.inbound_seq is not None and (
+            isinstance(self.inbound_seq, bool)
+            or not isinstance(self.inbound_seq, int)
+            or self.inbound_seq < 0
+        ):
+            raise ValueError("inbound_seq must be a non-negative integer when present")