bazaar-contrib-messages-node 0.3.0rc1__py3-none-any.whl

bazaar_contrib_messages_node/__init__.py

@@ -0,0 +1,195 @@
+"""Agent-owned conversations, messages and resource-scoped commands."""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import AsyncIterator, Mapping
+from contextlib import AsyncExitStack, asynccontextmanager
+from copy import copy
+from pathlib import Path
+
+from bazaar_contrib_audit import AUDIT, Audit
+from bazaar_contrib_invoke import COMMANDS, CommandEntry
+from bazaar_contrib_legacy_node_migrations import LEGACY_NODE_MIGRATIONS
+from bazaar_contrib_messages import (
+    MESSAGES,
+    Actors,
+    Agent,
+    MessageSession,
+    Mode,
+    SessionBindingValidator,
+    ThreadConcurrency,
+)
+from bazaar_contrib_messages.operations import UnreadMessageOwner
+from bazaar_contrib_schema import SCHEMA
+from bazaar_contrib_storage import DB, Database, Session
+from bazaar_contrib_timer import TIMER, Timer
+from bazaar_core import Context, Contrib, ContribSpec
+from pydantic import BaseModel, ConfigDict, Field, StrictStr
+lazy from bazaar_contrib_channel import Channel
+lazy from bazaar_contrib_sidecar import CLIENT
+
+from .attachments import AttachmentMaterializer
+from .concurrency import ThreadLockRegistry
+from .dispatch import CommandDispatcher
+from .repository import Repository
+from .repository.unread import list_unread_message_owners
+from .schema import MODULE
+from .service import NodeMessageService
+from .store import MessageStore
+lazy from .cli._client import MessageClient
+lazy from .cli.inbox import inbox
+lazy from .cli.message import message
+lazy from .cli.thread import thread
+
+__all__ = [
+    "MESSAGES",
+    "AttachmentMaterializer",
+    "CommandDispatcher",
+    "MessageStore",
+    "NodeMessageService",
+    "NodeMessages",
+    "ThreadLockRegistry",
+    "commands",
+    "inbox_entry",
+    "message_entry",
+    "messages",
+    "thread_entry",
+]
+
+
+class _AgentRequest(BaseModel):
+    model_config = ConfigDict(extra="ignore", strict=True)
+    agent_id: StrictStr = Field(min_length=1)
+
+
+class NodeMessages:
+    """Keep command bindings within their owning agent's lifespan."""
+
+    def __init__(self, database: Database, audit: Audit, timer: Timer):
+        self.database = database
+        self.audit = audit
+        self.timer = timer
+        self._bindings: dict[Agent, CommandDispatcher] = {}
+
+    def storage(self, owner: Agent) -> MessageStore:
+        return MessageStore(self.database, owner, owner.id)
+
+    def in_session(self, session: Session, owner: Agent) -> MessageSession:
+        return Repository(session, owner, owner.id)
+
+    async def list_unread_message_owners(self) -> tuple[UnreadMessageOwner, ...]:
+        return await self.database.read(list_unread_message_owners)
+
+    @asynccontextmanager
+    async def bind(
+        self,
+        *,
+        actors: Actors,
+        name: str,
+        channel: Channel,
+        workspace: Path,
+        concurrency: ThreadConcurrency,
+        provider_timeout: float,
+        shutdown_timeout: float,
+        session_binding_validator: SessionBindingValidator | None = None,
+    ) -> AsyncIterator[NodeMessageService]:
+        owner = Agent(actors.agent_id)
+        if owner in self._bindings:
+            raise ValueError(
+                f"message commands are already bound for agent: {owner.id}"
+            )
+        service = NodeMessageService(
+            storage=MessageStore(self.database, owner, name),
+            audit=self.audit,
+            concurrency=concurrency,
+            channel=channel,
+            workspace=workspace,
+            provider_timeout=provider_timeout,
+            timer=self.timer,
+        )
+        await service._attachments.reconcile()
+        dispatcher = CommandDispatcher(
+            service, actors=actors, session_binding_validator=session_binding_validator
+        )
+        dispatcher.start_accepting()
+        self._bindings[owner] = dispatcher
+        try:
+            yield service
+        finally:
+            dispatcher.stop_accepting()
+            del self._bindings[owner]
+            await dispatcher.drain(timeout=shutdown_timeout)
+
+    async def request(self, request: Mapping[str, object]) -> Mapping[str, object]:
+        owner = Agent(_AgentRequest.model_validate(request).agent_id)
+        dispatcher = self._bindings.get(owner)
+        if dispatcher is None:
+            return {
+                "ok": False,
+                "code": "SERVICE_NOT_READY",
+                "error": "command service is not accepting requests",
+            }
+        return await dispatcher(request)
+
+
+@asynccontextmanager
+async def lifespan(ctx: Context):
+    async with ctx.accept(SCHEMA).register(MODULE):
+        ctx.offer(
+            MESSAGES, NodeMessages(ctx.accept(DB), ctx.accept(AUDIT), ctx.accept(TIMER))
+        )
+        yield
+
+
+@asynccontextmanager
+async def cli_lifespan(ctx: Context):
+    client = ctx.accept(CLIENT)
+    timeout = client.timeout
+    client.timeout = None
+    try:
+        async with AsyncExitStack() as stack:
+            groups = [message, thread]
+            if os.environ.get("BCN_AGENT_MODE") == Mode.DANGEROUS_INDIVIDUAL.value:
+                groups.append(inbox)
+            for group in groups:
+                group = copy(group)
+                group.context_settings = {
+                    **group.context_settings,
+                    "obj": MessageClient(client.context),
+                }
+                stack.enter_context(ctx.accept(COMMANDS).register(group))
+            yield
+    finally:
+        client.timeout = timeout
+
+
+messages = Contrib(
+    accepts=[SCHEMA, LEGACY_NODE_MIGRATIONS, DB, AUDIT, TIMER],
+    offers=[MESSAGES],
+    lifespan=lifespan,
+)
+commands = Contrib(accepts=[CLIENT, COMMANDS], lifespan=cli_lifespan)
+_TRANSPORT = ContribSpec(
+    contrib="sidecar-windows" if sys.platform == "win32" else "sidecar-unix",
+    config={"endpoint": os.environ.get("BCN_ENDPOINT")},
+)
+message_entry = CommandEntry(
+    contrib="messages-cli", help="Message operations", dependencies=(_TRANSPORT,)
+)
+thread_entry = CommandEntry(
+    contrib="messages-cli",
+    help="Thread attention operations",
+    dependencies=(_TRANSPORT,),
+)
+
+inbox_entry = (
+    CommandEntry(
+        contrib="messages-cli",
+        help="Inbox target summary operations",
+        dependencies=(_TRANSPORT,),
+    )
+    if os.environ.get("BCN_AGENT_MODE") == Mode.DANGEROUS_INDIVIDUAL.value
+    else None
+)

bazaar_contrib_messages_node/attachments.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import asyncio
+import mimetypes
+import os
+import re
+import tempfile
+from collections.abc import AsyncIterable, Awaitable, Callable, Collection
+from pathlib import Path, PurePosixPath
+from uuid import UUID
+
+from bazaar_contrib_messages.models import InboundAttachment
+
+_SAFE_SUFFIX = re.compile(r"^\.[A-Za-z0-9]{1,10}$")
+
+
+class AttachmentMaterializer:
+    def __init__(
+        self,
+        workspace: Callable[[], Path],
+        referenced_paths: Callable[[], Awaitable[Collection[str]]],
+        *,
+        max_file_bytes: int = 25 * 1024 * 1024,
+    ) -> None:
+        self._workspace = workspace
+        self._referenced_paths = referenced_paths
+        self._max_file_bytes = max_file_bytes
+
+    async def reconcile(self) -> None:
+        root = self._workspace() / "attachments"
+        await asyncio.to_thread(root.mkdir, parents=True, exist_ok=True, mode=0o700)
+        files = await asyncio.to_thread(
+            lambda: tuple(
+                path
+                for path in root.iterdir()
+                if path.is_file() and not path.is_symlink()
+            )
+        )
+        referenced = set(await self._referenced_paths())
+        for path in files:
+            if not (path.name.startswith(".bcn-") and path.name.endswith(".part")):
+                try:
+                    UUID(path.stem)
+                except ValueError:
+                    continue
+            if str(PurePosixPath("attachments", path.name)) in referenced:
+                continue
+            await asyncio.to_thread(path.unlink)
+
+    async def _stage(
+        self,
+        source: AsyncIterable[bytes],
+        destination: Path,
+    ) -> int:
+        """Write an attachment aside, then move it into place once it is whole."""
+
+        descriptor, temporary = await asyncio.to_thread(
+            tempfile.mkstemp,
+            dir=destination.parent,
+            prefix=".bcn-",
+            suffix=".part",
+        )
+        temporary = Path(temporary)
+        try:
+            try:
+                size = await self._write(descriptor, source)
+                await asyncio.to_thread(os.fsync, descriptor)
+                stored = await asyncio.to_thread(os.fstat, descriptor)
+                if stored.st_size != size:
+                    raise OSError(
+                        "attachment write size mismatch: "
+                        f"expected {size}, got {stored.st_size}"
+                    )
+            finally:
+                await asyncio.to_thread(os.close, descriptor)
+            await asyncio.to_thread(os.replace, temporary, destination)
+            if os.name != "nt":
+                await asyncio.to_thread(destination.chmod, 0o600)
+            return size
+        except BaseException:
+            if await asyncio.to_thread(temporary.exists):
+                await asyncio.to_thread(temporary.unlink)
+            raise
+
+    async def _write(
+        self,
+        descriptor: int,
+        source: AsyncIterable[bytes],
+    ) -> int:
+        """Write the source through, refusing it the moment it goes over a limit."""
+
+        size = 0
+        async for chunk in source:
+            size += len(chunk)
+            if size > self._max_file_bytes:
+                raise ValueError("attachment exceeds the per-file size limit")
+            await asyncio.to_thread(_write_all, descriptor, chunk)
+        return size
+
+    async def materialize(
+        self,
+        source: AsyncIterable[bytes],
+        *,
+        attachment_id: str,
+        name: str,
+        kind: str,
+        media_type: str | None = None,
+    ) -> InboundAttachment:
+        if not name or not kind:
+            raise ValueError("attachment name and kind must be non-empty")
+        suffix = await asyncio.to_thread(_attachment_suffix, name, media_type)
+        relative = PurePosixPath("attachments", f"{attachment_id}{suffix.lower()}")
+        root = self._workspace() / "attachments"
+        destination = self._workspace().joinpath(*relative.parts)
+        await asyncio.to_thread(root.mkdir, parents=True, exist_ok=True, mode=0o700)
+        size = await self._stage(source, destination)
+        return InboundAttachment(
+            attachment_id=attachment_id,
+            name=Path(name).name,
+            kind=kind,
+            state="ready",
+            media_type=media_type,
+            relative_path=str(relative),
+            size_bytes=size,
+        )
+
+    def failed(
+        self,
+        *,
+        attachment_id: str,
+        name: str,
+        kind: str,
+        error: str | None,
+        media_type: str | None = None,
+    ) -> InboundAttachment:
+        return InboundAttachment(
+            attachment_id=attachment_id,
+            name=Path(name).name or "attachment.bin",
+            kind=kind,
+            state="failed",
+            media_type=media_type,
+            error=error,
+        )
+
+
+def _write_all(descriptor: int, payload: bytes) -> None:
+    view = memoryview(payload)
+    while view:
+        written = os.write(descriptor, view)
+        if written == 0:
+            raise OSError("attachment write made no progress")
+        view = view[written:]
+
+
+def _attachment_suffix(name: str, media_type: str | None) -> str:
+    suffix = Path(name).suffix
+    if _SAFE_SUFFIX.fullmatch(suffix):
+        return suffix
+    media_type = (media_type or "").partition(";")[0].strip().lower()
+    if not media_type or media_type.endswith("/octet-stream"):
+        return ""
+    guessed = mimetypes.guess_extension(media_type) or ""
+    return guessed if _SAFE_SUFFIX.fullmatch(guessed) else ""
+
+
+__all__ = ["AttachmentMaterializer"]

bazaar_contrib_messages_node/cli/__init__.py

@@ -0,0 +1 @@
+"""Native message and thread commands contributed to bcc."""

bazaar_contrib_messages_node/cli/_client.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Coroutine, Mapping
+from functools import wraps
+from typing import Any, cast
+
+import click
+from bazaar_contrib_sidecar import Remote, Symbol
+
+
+class BccCommandError(RuntimeError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str,
+        draft_saved: bool | None = None,
+        next_action: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.draft_saved = draft_saved
+        self.next_action = next_action
+
+
+def _environment(name: str, code: str) -> str:
+    value = os.environ.get(name)
+    if not value:
+        raise BccCommandError(f"{name} is not set", code=code)
+    return value
+
+
+class MessageClient:
+    def __init__(self, remote: Remote):
+        self.remote = remote
+
+    async def request(
+        self, resource: str, command: str, payload: Mapping[str, object] = {}
+    ) -> Mapping[str, object]:
+        """Wait for the node's own command budget and complete send outcome."""
+        request: dict[str, object] = {
+            "kind": "command",
+            "resource": resource,
+            "command": command,
+            "agent_id": _environment("BCN_AGENT_ID", "AGENT_REQUIRED"),
+            "actor_id": _environment("BCN_ACTOR_ID", "SESSION_REQUIRED"),
+            "runtime_session_id": _environment(
+                "BCN_RUNTIME_SESSION_ID", "SESSION_BINDING_REQUIRED"
+            ),
+            "session_capability": _environment(
+                "BCN_COMMAND_CAPABILITY", "SESSION_BINDING_REQUIRED"
+            ),
+            **payload,
+        }
+        service = cast(
+            Remote,
+            await self.remote.call(
+                "accept", Symbol("bazaar_contrib_messages:MESSAGES")
+            ),
+        )
+        response = cast(Mapping[str, object], await service.call("request", request))
+        if response.get("ok") is not True:
+            raise BccCommandError(
+                str(response.get("error", "command failed")),
+                code=str(response.get("code", "COMMAND_FAILED")),
+                draft_saved=response.get("draft_saved") is True,
+                next_action=str(response["next_action"])
+                if response.get("next_action") is not None
+                else None,
+            )
+        return cast(Mapping[str, object], response["result"])
+
+
+def run[**P](
+    command: Callable[P, Coroutine[Any, Any, None]],
+) -> Callable[P, Coroutine[Any, Any, None]]:
+    """Return the command body to invoke's owning event loop."""
+
+    @wraps(command)
+    async def invoke(*args: P.args, **kwargs: P.kwargs) -> None:
+        try:
+            await command(*args, **kwargs)
+        except BccCommandError as error:
+            from ._format import print_error
+
+            print_error(error)
+            raise click.exceptions.Exit(1) from error
+
+    return invoke

bazaar_contrib_messages_node/cli/_format.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import re
+import sys
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from html import escape
+from typing import Annotated, cast
+
+import click
+from pydantic import BaseModel, ConfigDict, Field, StrictStr, ValidationError
+
+from ..dispatch import format_check_message, format_read_message
+from ..rendering import TextTemplate
+from ._client import BccCommandError
+
+
+def echo(text: str) -> None:
+    click.echo(text)
+
+
+def print_error(error: BccCommandError) -> None:
+    click.echo(
+        _ERROR.render(
+            {
+                "message": str(error),
+                "code": error.code,
+                "draft_saved": error.draft_saved,
+                "next_action": error.next_action,
+            }
+        ),
+        file=sys.stderr,
+    )
+
+
+_INBOX_CHECK = TextTemplate.from_resource("bcc/inbox_check.tpl")
+
+
+_CHECK = TextTemplate.from_resource("bcc/check.tpl")
+
+
+_READ = TextTemplate.from_resource("bcc/read.tpl")
+
+
+_SEARCH = TextTemplate.from_resource("bcc/search.tpl")
+
+
+_UNFOLLOW = TextTemplate.from_resource("bcc/unfollow.tpl")
+
+
+_ERROR = TextTemplate.from_resource("bcc/error.tpl")
+
+
+def serialize_inbox_check(result: Mapping[str, object]) -> str:
+    targets = cast(list[Mapping[str, object]], result["targets"])
+    return _INBOX_CHECK.render(
+        {
+            "target_lines": [
+                " ".join(
+                    (
+                        f"[target={target['target']}",
+                        f"pending={target['pending_count']}",
+                        f"latest-msg={target['latest_message_id']}]",
+                    )
+                )
+                for target in targets
+            ]
+        }
+    )
+
+
+def serialize_check(result: Mapping[str, object]) -> str:
+    messages = cast(list[Mapping[str, object]], result["messages"])
+    referenced_messages = cast(
+        list[Mapping[str, object]], result["referenced_messages"]
+    )
+    return _CHECK.render(
+        {
+            "referenced_lines": [
+                format_read_message(
+                    message,
+                    index=index,
+                    count=len(referenced_messages),
+                )
+                for index, message in enumerate(referenced_messages, start=1)
+            ],
+            "message_lines": [format_check_message(message) for message in messages],
+        }
+    )
+
+
+def serialize_read(result: Mapping[str, object]) -> str:
+    messages = cast(list[Mapping[str, object]], result["messages"])
+    referenced_messages = cast(
+        list[Mapping[str, object]], result["referenced_messages"]
+    )
+    return _READ.render(
+        {
+            "shown": len(messages),
+            "first_seq": result["first_seq"] if messages else None,
+            "last_seq": result["last_seq"] if messages else None,
+            "referenced_lines": [
+                format_read_message(
+                    message,
+                    index=index,
+                    count=len(referenced_messages),
+                )
+                for index, message in enumerate(referenced_messages, start=1)
+            ],
+            "message_lines": [
+                format_read_message(message, index=index, count=len(messages))
+                for index, message in enumerate(messages, start=1)
+            ],
+        }
+    )
+
+
+class _MessageSendResponse(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    text: Annotated[StrictStr, Field(min_length=1)]
+
+
+def serialize_send(result: Mapping[str, object]) -> str:
+    try:
+        return _MessageSendResponse.model_validate(result).text
+    except ValidationError as error:
+        raise BccCommandError(
+            "Message send returned an invalid response.",
+            code="SEND_RESPONSE_INVALID",
+        ) from error
+
+
+def _search_text(text: str, *, references: bool = True) -> str:
+    text = re.sub(
+        r"</?(?:result|preview|match)\b[^>]*>|<omit\s*/>",
+        lambda match: escape(match[0], quote=False),
+        text,
+        flags=re.IGNORECASE,
+    )
+    if not references:
+        return text
+    text = re.sub(r"\bdm:@([A-Za-z0-9][A-Za-z0-9_-]*)", r"dm:user:\1", text)
+    text = re.sub(r"\btask #([0-9]+)\b", r"task:\1", text)
+    text = re.sub(r"(^|[\n\s([{\"'`;])@([A-Za-z0-9][A-Za-z0-9_-]*)", r"\1user:\2", text)
+    return re.sub(r"(^|[\n\s([{\"'`;])#([A-Za-z][A-Za-z0-9_-]*)", r"\1channel:\2", text)
+
+
+def serialize_search(result: Mapping[str, object]) -> str:
+    messages = cast(list[Mapping[str, object]], result["messages"])
+    hits: list[dict[str, object]] = []
+    for message in messages:
+        sender = cast(Mapping[str, object] | None, message["sender"])
+        timestamp = datetime.fromtimestamp(
+            cast(int, message["at_ms"]) / 1000, tz=UTC
+        ).astimezone()
+        offset = timestamp.strftime("%z")
+        hits.append(
+            {
+                "source": _search_text(cast(str, message["target"]), references=False),
+                "message_id": message["message_id"],
+                "timestamp": (
+                    f"{timestamp:%Y-%m-%d %H:%M:%S} {offset[:3]}:{offset[3:]}"
+                ),
+                "sender_kind": message["sender_kind"],
+                "sender": _search_text(
+                    "self"
+                    if message["direction"] == "outbound"
+                    else cast(str, sender.get("name") or sender.get("id") or "unknown")
+                    if sender is not None
+                    else "unknown"
+                ),
+                "preview": "".join(
+                    "<match>" + _search_text(text) + "</match>"
+                    if matched
+                    else _search_text(text)
+                    for text, matched in cast(list[tuple[str, bool]], message["parts"])
+                ),
+            }
+        )
+    return _SEARCH.render({**result, "messages": hits})
+
+
+def serialize_unfollow(result: Mapping[str, object]) -> str:
+    return _UNFOLLOW.render(
+        {
+            "target": cast(str, result["target"]),
+            "changed": cast(bool, result["changed"]),
+        }
+    )

bazaar_contrib_messages_node/cli/inbox.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import click
+
+from ._client import MessageClient, run
+from ._format import echo, serialize_inbox_check
+
+
+@click.group(help="Inbox target summary operations")
+def inbox() -> None: ...
+
+
+@inbox.command(
+    "check",
+    help="Show pending inbox targets without draining or reading message content.",
+)
+@click.pass_obj
+@run
+async def check_targets(client: MessageClient) -> None:
+    echo(serialize_inbox_check(await client.request("inbox", "check", {})))
+
+
+__all__ = ["inbox"]