bazaar-compute-node 0.2.1rc14__tar.gz → 0.2.2rc1__tar.gz

{bazaar_compute_node-0.2.1rc14 → bazaar_compute_node-0.2.2rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bazaar-compute-node
-Version: 0.2.1rc14
+Version: 0.2.2rc1
 Summary: Runtime-agnostic computer node daemon for agents and channels.
 License-Expression: AGPL-3.0-only
 License-File: LICENSE

{bazaar_compute_node-0.2.1rc14 → bazaar_compute_node-0.2.2rc1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bazaar-compute-node"
-version = "0.2.1rc14"
+version = "0.2.2rc1"
 description = "Runtime-agnostic computer node daemon for agents and channels."
 readme = "README.md"
 license = "AGPL-3.0-only"

{bazaar_compute_node-0.2.1rc14 → bazaar_compute_node-0.2.2rc1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "bazaar-compute-node"
-version = "0.2.1rc14"
+version = "0.2.2rc1"
 description = "Runtime-agnostic computer node daemon for agents and channels."
 readme = "README.md"
 license = "AGPL-3.0-only"

{bazaar_compute_node-0.2.1rc14 → bazaar_compute_node-0.2.2rc1}/src/bazaar_compute_node/app/application.py

@@ -20,7 +20,6 @@ from ..core.models import InboundAttachment, Message, RuntimeEventState
 from ..core.observability import AuditContext, IAudit
 from ..core.orchestration import ReminderScheduler
 from ..core.paths import resolve_data_dir, resolve_workspace_dir
-from ..core.restart import RESTART_EXIT_CODE
 from ..core.runtime import RuntimeAvailability, RuntimeDescription, RuntimeModels
 from ..core.storage import IStorage
 from ..core.timerwheel import TimerWheel
@@ -204,17 +203,11 @@ class NodeApplication:
             version=__version__,
             interval_seconds=self.timeout_budget.startup_seconds,
         )
-        self._restart_requested = False
-        # Windows has nothing that brings the node back after it exits, so
-        # there it offers no upgrade command at all
-        self.upgrade_service = (
-            None
-            if os.name == "nt"
-            else UpgradeService(
-                available_version=self.version_watcher.available_version,
-                installed_version=__version__,
-                request_restart=self.request_restart,
-            )
+        self._stopped = asyncio.Event()
+        self.upgrade_service = UpgradeService(
+            available_version=self.version_watcher.available_version,
+            installed_version=__version__,
+            request_stop=self._stopped.set,
         )
         self.command_server = LocalCommandServer(
             self._dispatch,
@@ -226,7 +219,6 @@ class NodeApplication:
         self._started = False
         self._ready = False
         self._accepting = False
-        self._stopped = asyncio.Event()
         self._logger = logging.getLogger("bazaar_compute_node.application")
 
     @property
@@ -865,16 +857,6 @@ class NodeApplication:
         if errors:
             self._log("bcn.stop.errors", errors=errors)
 
-    def request_restart(self) -> None:
-        """Stop, and tell whatever hosts this node to start it again."""
-
-        self._restart_requested = True
-        self._stopped.set()
-
-    @property
-    def exit_code(self) -> int:
-        return RESTART_EXIT_CODE if self._restart_requested else 0
-
     async def wait(self) -> None:
         loop = asyncio.get_running_loop()
         for signum in (signal.SIGINT, signal.SIGTERM):

{bazaar_compute_node-0.2.1rc14 → bazaar_compute_node-0.2.2rc1}/src/bazaar_compute_node/app/attachments.py

@@ -21,12 +21,10 @@ class AttachmentMaterializer:
         referenced_paths: Callable[[], Awaitable[set[str]]],
         *,
         max_file_bytes: int = 25 * 1024 * 1024,
-        max_workspace_bytes: int = 1024 * 1024 * 1024,
     ) -> None:
         self._workspace = workspace
         self._referenced_paths = referenced_paths
         self._max_file_bytes = max_file_bytes
-        self._max_workspace_bytes = max_workspace_bytes
         self._lock = asyncio.Lock()
 
     async def reconcile(self) -> None:
@@ -66,11 +64,9 @@ class AttachmentMaterializer:
         source: bytes | AsyncIterable[bytes],
         temporary: Path,
         destination: Path,
-        root: Path,
     ) -> int:
         """Write an attachment aside, then move it into place once it is whole."""
 
-        current_size = await asyncio.to_thread(self._stored_size, root)
         descriptor: int | None = None
         try:
             descriptor = await asyncio.to_thread(
@@ -80,7 +76,7 @@ class AttachmentMaterializer:
                 0o600,
             )
             try:
-                size = await self._write(descriptor, source, current_size)
+                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:
@@ -107,12 +103,12 @@ class AttachmentMaterializer:
         self,
         descriptor: int,
         source: bytes | AsyncIterable[bytes],
-        current_size: int,
     ) -> int:
         """Write the source through, refusing it the moment it goes over a limit."""
 
         if isinstance(source, bytes):
-            self._check_room(len(source), current_size)
+            if len(source) > self._max_file_bytes:
+                raise ValueError("attachment exceeds the per-file size limit")
             await asyncio.to_thread(_write_all, descriptor, source)
             return len(source)
         size = 0
@@ -120,16 +116,11 @@ class AttachmentMaterializer:
             if not isinstance(chunk, bytes):
                 raise TypeError("attachment stream must yield bytes")
             size += len(chunk)
-            self._check_room(size, current_size)
+            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
 
-    def _check_room(self, size: int, current_size: int) -> None:
-        if size > self._max_file_bytes:
-            raise ValueError("attachment exceeds the per-file size limit")
-        if current_size + size > self._max_workspace_bytes:
-            raise ValueError("attachment workspace quota exceeded")
-
     async def materialize(
         self,
         source: bytes | AsyncIterable[bytes],
@@ -153,7 +144,7 @@ class AttachmentMaterializer:
             await asyncio.to_thread(
                 staging.mkdir, parents=True, exist_ok=True, mode=0o700
             )
-            size = await self._stage(source, temporary, destination, root)
+            size = await self._stage(source, temporary, destination)
         return InboundAttachment(
             attachment_id=attachment_id,
             name=Path(name).name,
@@ -181,17 +172,6 @@ class AttachmentMaterializer:
             error=error,
         )
 
-    @staticmethod
-    def _stored_size(root: Path) -> int:
-        if not root.exists():
-            return 0
-        return sum(
-            path.stat().st_size
-            for pattern in ("*/content", "*/content.*")
-            for path in root.glob(pattern)
-            if path.is_file() and not path.is_symlink()
-        )
-
 
 def _write_all(descriptor: int, payload: bytes) -> None:
     view = memoryview(payload)

{bazaar_compute_node-0.2.1rc14 → bazaar_compute_node-0.2.2rc1}/src/bazaar_compute_node/app/resource_dispatch.py

@@ -273,8 +273,6 @@ class CommandDispatcher(_MessageCommandDispatcher):
         if resource == "node":
             upgrade_service = self._upgrade_service
             if upgrade_service is None:
-                # nothing on this platform would bring the node back after an
-                # upgrade exits it, so the Agent is given no upgrade to run
                 raise CommandDispatchError(
                     "UNKNOWN_RESOURCE",
                     f"unsupported command resource: {resource}",

{bazaar_compute_node-0.2.1rc14 → bazaar_compute_node-0.2.2rc1}/src/bazaar_compute_node/app/system_service.py

@@ -14,6 +14,7 @@ import sys
 import tempfile
 import time
 from dataclasses import dataclass
+from importlib.resources import files
 from pathlib import Path
 
 from ..core.paths import resolve_data_dir
@@ -43,6 +44,7 @@ class SystemServiceContext:
     """Resolved paths used to render one user-level system service."""
 
     executable: Path | None
+    python: Path
     config_path: Path
     data_dir: Path
     env_file: Path
@@ -97,6 +99,7 @@ def _build_context(
     env_file = env_file.resolve()
     return SystemServiceContext(
         executable=executable,
+        python=Path(vars(sys)["_base_executable"]).resolve(),
         config_path=config_path,
         data_dir=data_dir,
         env_file=env_file,
@@ -196,6 +199,8 @@ def _render_systemd_unit(context: SystemServiceContext) -> str:
         {
             "managed_marker": MANAGED_MARKER,
             "executable": _systemd_quote(_require_executable(context)),
+            "python": _systemd_quote(context.python),
+            "supervisor_path": _systemd_quote(context.data_dir / "supervisor.py"),
             "config_path": _systemd_quote(context.config_path),
             "data_dir": _systemd_quote(context.data_dir, quote=False),
             "home_environment": _systemd_quote(f"BCN_HOME={context.data_dir.parent}"),
@@ -222,6 +227,8 @@ def _render_launchd_plist(
             "config_path": str(context.config_path),
             "environment_file": str(context.env_file),
             "executable": str(_require_executable(context)),
+            "python": str(context.python),
+            "supervisor_path": str(context.data_dir / "supervisor.py"),
             "log_path": str(context.log_path),
         }
     ).encode("utf-8")
@@ -232,6 +239,8 @@ def _render_windows_wrapper(context: SystemServiceContext) -> str:
         {
             "managed_marker": MANAGED_MARKER,
             "executable": _powershell_literal(_require_executable(context)),
+            "python": _powershell_literal(context.python),
+            "supervisor_path": _powershell_literal(context.data_dir / "supervisor.py"),
             "config_path": _powershell_literal(context.config_path),
             "home_dir": _powershell_literal(context.data_dir.parent),
             "environment_script": _powershell_literal(context.env_file),
@@ -375,6 +384,7 @@ def _windows_paths(data_dir: Path) -> tuple[Path, Path, Path]:
 
 
 def _install_linux(context: SystemServiceContext) -> None:
+    _install_supervisor(context)
     unit_path = _systemd_unit_path()
     _write_managed_file(unit_path, _render_systemd_unit(context), mode=0o600)
     _run_native_command(["systemctl", "--user", "daemon-reload"])
@@ -387,6 +397,7 @@ def _install_linux(context: SystemServiceContext) -> None:
 
 
 def _install_macos(context: SystemServiceContext) -> None:
+    _install_supervisor(context)
     plist_path, wrapper_path = _launchd_paths()
     _write_managed_file(
         wrapper_path,
@@ -406,6 +417,7 @@ def _install_macos(context: SystemServiceContext) -> None:
 
 
 def _install_windows(context: SystemServiceContext) -> None:
+    _install_supervisor(context)
     xml_path, wrapper_path, launcher_path = _windows_paths(context.data_dir)
     context.data_dir.mkdir(parents=True, exist_ok=True)
     _write_managed_file(
@@ -441,6 +453,16 @@ def _install_windows(context: SystemServiceContext) -> None:
     print(f"Start with: schtasks /Run /TN {WINDOWS_TASK_NAME}", flush=True)
 
 
+def _install_supervisor(context: SystemServiceContext) -> None:
+    _write_managed_file(
+        context.data_dir / "supervisor.py",
+        files("bazaar_compute_node")
+        .joinpath("resources/system_service/supervisor.py")
+        .read_bytes(),
+        mode=0o600,
+    )
+
+
 def default_env_file() -> Path:
     """The environment file a service reads unless told another, in the
     platform's format."""
@@ -568,18 +590,21 @@ def _stop_macos() -> None:
 
 def _managed_windows_process_ids(context: SystemServiceContext) -> tuple[int, ...]:
     config_path = _powershell_literal(context.config_path)
+    supervisor_path = _powershell_literal(context.data_dir / "supervisor.py")
     script = "\n".join(
         (
             "$ErrorActionPreference = 'Stop'",
             "$queryProcessId = $PID",
             f"$configPath = [IO.Path]::GetFullPath({config_path}).ToLowerInvariant()",
+            f"$supervisorPath = [IO.Path]::GetFullPath({supervisor_path}).ToLowerInvariant()",
             "Get-CimInstance -ClassName Win32_Process |",
             "    Where-Object {",
             "        $_.ProcessId -ne $queryProcessId -and",
             "        $_.CommandLine -and",
             "        $_.CommandLine.ToLowerInvariant().Contains($configPath) -and",
-            r"        $_.CommandLine -match '(?i)(^|\s)run(\s|$)' -and",
-            r"        $_.CommandLine -match '(?i)(^|\s)--config(\s|$)'",
+            r"        $_.CommandLine -match '(?i)(^|\s)--config(\s|$)' -and",
+            "        ($_.CommandLine.ToLowerInvariant().Contains($supervisorPath) -or",
+            r"         $_.CommandLine -match '(?i)(^|\s)run(\s|$)')",
             "    } |",
             "    ForEach-Object { $_.ProcessId }",
             "",
@@ -721,6 +746,10 @@ def _uninstall(context: SystemServiceContext) -> None:
         _uninstall_windows(context)
     else:
         raise RuntimeError(f"unsupported host service platform: {system}")
+    _remove_managed_file(context.data_dir / "supervisor.py")
+    (
+        context.data_dir / ("bcn.running.exe" if os.name == "nt" else "bcn.running")
+    ).unlink(missing_ok=True)
 
 
 def _status_linux() -> NativeServiceStatus:

{bazaar_compute_node-0.2.1rc14 → bazaar_compute_node-0.2.2rc1}/src/bazaar_compute_node/app/upgrade.py

@@ -70,7 +70,8 @@ def _install(version: str) -> None:
             _uv_executable(),
             "tool",
             "install",
-            "--force",
+            # Reuse the tool environment: --force would remove its running
+            # Python interpreter on Windows, even with a copied entry point.
             # the release was announced by PyPI's own API minutes ago, while uv
             # resolves against a separately cached index that can still predate
             # it and would then report the version as one that does not exist
@@ -90,11 +91,11 @@ class UpgradeService:
         *,
         available_version: Callable[[], str | None],
         installed_version: str,
-        request_restart: Callable[[], None],
+        request_stop: Callable[[], None],
     ) -> None:
         self._available_version = available_version
         self._installed_version = installed_version
-        self._request_restart = request_restart
+        self._request_stop = request_stop
         self._lock = asyncio.Lock()
 
     @property
@@ -134,10 +135,7 @@ class UpgradeService:
                 raise UpgradeError(f"{version!r} is not a release version") from error
             await self.install(version)
             reminder_id = await wake_after(version)
-            # the node cannot restart itself from the inside: on Windows the
-            # stop it would ask for kills the process tree it is asking from.
-            # Exiting is the one thing it can do that its host watches for.
-            self._request_restart()
+            self._request_stop()
             return version, reminder_id
 
     async def install(self, version: str) -> None:

{bazaar_compute_node-0.2.1rc14 → bazaar_compute_node-0.2.2rc1}/src/bazaar_compute_node/cmd/bcc/__init__.py

@@ -36,13 +36,10 @@ for group in (message, thread, reminder):
 if os.environ.get("BCN_AGENT_MODE") == Mode.DANGEROUS_INDIVIDUAL.value:
     bcc.add_command(inbox)
 
-# Windows has nothing that brings the node back after an upgrade exits it, so
-# there the node offers no upgrade and the commands would only ever be refused
-if os.name != "nt":
-    bcc.add_command(node)
-    # `bcc upgrade` reads better than `bcc node upgrade`, so the command line name
-    # and the resource it addresses differ here
-    bcc.add_command(node.commands["upgrade"], "upgrade")
+bcc.add_command(node)
+# `bcc upgrade` reads better than `bcc node upgrade`, so the command line name
+# and the resource it addresses differ here
+bcc.add_command(node.commands["upgrade"], "upgrade")
 
 
 def main(argv: Sequence[str] | None = None) -> int:

{bazaar_compute_node-0.2.1rc14 → bazaar_compute_node-0.2.2rc1}/src/bazaar_compute_node/cmd/bcn/node.py

@@ -175,7 +175,7 @@ async def _run_node(args: argparse.Namespace, parser: Usage) -> int:
         except TimeoutError:
             print("bcn stop timed out; ending runtimes", file=sys.stderr, flush=True)
         await children.end_all()
-    return node.exit_code
+    return 0
 
 
 def build_node_commands(translator: Translator) -> tuple[click.Command, ...]:

{bazaar_compute_node-0.2.1rc14 → bazaar_compute_node-0.2.2rc1}/src/bazaar_compute_node/contrib/wecom/channel.py

@@ -43,7 +43,7 @@ from ...core.timerwheel import TimerWheel
 from ...core.utils.clock import remaining
 from ...core.utils.markdown import split_markdown, utf8_bytes
 from ...i18n import ENGLISH, Translator, create_translator
-from .identity import conversation_thread_id, parse_provider_thread_id
+from .identity import TopicAddress, conversation_thread_id, parse_provider_thread_id
 from .outbound import (
     AttachmentReader,
     PreparedAttachment,
@@ -52,6 +52,7 @@ from .outbound import (
     prepare_attachments,
     visible_message_body,
 )
+from .topic import TopicConversations
 
 _STOP = object()
 _MAX_MEDIA_BYTES = 25 * 1024 * 1024
@@ -198,6 +199,13 @@ class WeComChannel(IChannel):
             self._logger.addHandler(logging.StreamHandler())
         self._logger.setLevel(logging.INFO)
         self._logger.propagate = False
+        self._topics = TopicConversations(
+            context,
+            bot_id=bot_id,
+            secret=secret,
+            emit=self._inbound.put,
+            logger=self._logger,
+        )
 
     @property
     def name(self) -> str:
@@ -241,6 +249,7 @@ class WeComChannel(IChannel):
         self._startup_finished.clear()
         self._startup_error = None
         self._state = "connecting"
+        self._topics.start()
         self._runner = asyncio.create_task(self._run(), name="bcn-wecom-channel")
         try:
             await asyncio.wait_for(self._startup_finished.wait(), timeout=timeout)
@@ -249,46 +258,57 @@ class WeComChannel(IChannel):
             self._runner.cancel()
             await asyncio.gather(self._runner, return_exceptions=True)
             self._runner = None
+            await self._topics.stop(timeout=timeout)
             self._state = "stopped"
             raise
         if self._startup_error is not None:
+            await self._topics.stop(timeout=timeout)
             raise self._startup_error
 
     async def stop(self, *, timeout: float) -> None:
         self._stopping.set()
-        decided_at_ms = time_ns() // 1_000_000
-        for pending in tuple(self._pending_approvals.values()):
-            if not pending.future.done():
-                pending.future.set_result(
-                    ApprovalResult(
-                        request_id=pending.request.approval.request_id,
-                        decision=ApprovalDecision.REJECTED,
-                        decided_at_ms=decided_at_ms,
-                        reason="channel_stopped",
-                    )
-                )
-        self._pending_approvals.clear()
-        self._approval_task_ids_by_request.clear()
-        await self._cancel_approval_card_updates()
+        deadline = asyncio.get_running_loop().time() + timeout
+        shutdown = asyncio.create_task(
+            self._topics.stop(timeout=timeout), name="bcn-wecom-topics-stop"
+        )
         try:
-            await asyncio.wait_for(self._send_lock.acquire(), timeout=timeout)
-        except TimeoutError:
-            pass
-        else:
-            self._send_lock.release()
-        connection = self._connection
-        if connection is not None:
-            await connection.close()
-        runner = self._runner
-        if runner is not None:
+            decided_at_ms = time_ns() // 1_000_000
+            for pending in tuple(self._pending_approvals.values()):
+                if not pending.future.done():
+                    pending.future.set_result(
+                        ApprovalResult(
+                            request_id=pending.request.approval.request_id,
+                            decision=ApprovalDecision.REJECTED,
+                            decided_at_ms=decided_at_ms,
+                            reason="channel_stopped",
+                        )
+                    )
+            self._pending_approvals.clear()
+            self._approval_task_ids_by_request.clear()
+            await self._cancel_approval_card_updates()
             try:
-                await asyncio.wait_for(runner, timeout=timeout)
+                await asyncio.wait_for(
+                    self._send_lock.acquire(), timeout=remaining(deadline)
+                )
             except TimeoutError:
-                runner.cancel()
-                await asyncio.gather(runner, return_exceptions=True)
-        self._runner = None
-        self._state = "stopped"
-        await self._inbound.put(_STOP)
+                pass
+            else:
+                self._send_lock.release()
+            connection = self._connection
+            if connection is not None:
+                await connection.close()
+            runner = self._runner
+            if runner is not None:
+                try:
+                    await asyncio.wait_for(runner, timeout=remaining(deadline))
+                except TimeoutError:
+                    runner.cancel()
+                    await asyncio.gather(runner, return_exceptions=True)
+        finally:
+            self._runner = None
+            await shutdown
+            self._state = "stopped"
+            await self._inbound.put(_STOP)
 
     async def receive(self) -> AsyncIterator[Message]:
         while True:
@@ -510,6 +530,24 @@ class WeComChannel(IChannel):
     async def send(
         self, request: ChannelSendRequest, *, timeout: float
     ) -> ProviderCallResult[ChannelDeliveryReceipt]:
+        try:
+            address = TopicAddress.parse(request.provider_thread_id)
+            if address is not None and address.bot_id != self._bot_id:
+                raise ValueError("WeCom topic belongs to another bot")
+        except ValueError as error:
+            return ProviderCallResult(
+                status=ProviderCallStatus.FAILED,
+                error_kind="invalid_topic_target",
+                error_message=str(error),
+            )
+        if address is not None:
+            if self._stopping.is_set():
+                return ProviderCallResult(
+                    status=ProviderCallStatus.FAILED,
+                    error_kind="channel_stopped",
+                    error_message="WeCom channel is stopping",
+                )
+            return await self._topics.send(request, address, timeout=timeout)
         _, target_id = parse_provider_thread_id(request.provider_thread_id)
         try:
             batches = (
@@ -945,6 +983,13 @@ class WeComChannel(IChannel):
     async def request_approval(
         self, request: ChannelApprovalRequest, *, timeout: float
     ) -> ApprovalResult:
+        if TopicAddress.parse(request.provider_thread_id) is not None:
+            return ApprovalResult(
+                request_id=request.approval.request_id,
+                decision=ApprovalDecision.REJECTED,
+                decided_at_ms=time_ns() // 1_000_000,
+                reason="WeCom native topics do not support approval cards",
+            )
         request_id = request.approval.request_id
         if timeout <= 0:
             raise TimeoutError("WeCom approval card delivery timed out")
@@ -1375,7 +1420,7 @@ class WeComChannel(IChannel):
         return False
 
     async def _receive_event(self, frame: Mapping[str, object]) -> None:
-        """Take in a bot event frame, which is only ever an approval decision."""
+        """Route native topic events and ordinary chat approval decisions."""
 
         body = frame.get("body")
         event = body.get("event") if isinstance(body, dict) else None
@@ -1387,6 +1432,8 @@ class WeComChannel(IChannel):
             "wecom.event.received",
             event_type=self._last_event_type,
         )
+        if isinstance(body, dict) and self._topics.receive(body):
+            return
         if (
             self._last_event_type == "template_card_event"
             and isinstance(event, dict)
@@ -1408,6 +1455,10 @@ class WeComChannel(IChannel):
         if not isinstance(body, dict):
             self._filter_message("invalid_body")
             return
+        compatibility = body.get("compat_info")
+        if isinstance(compatibility, dict) and compatibility.get("source") == "channel":
+            self._filter_message("native_topic_projection")
+            return
         route = self._route(body)
         if route is None:
             return

bazaar_compute_node-0.2.2rc1/src/bazaar_compute_node/contrib/wecom/identity.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from urllib.parse import quote, unquote
+
+_PROVIDER_PREFIX = "wecom"
+
+
+def conversation_thread_id(bot_id: str, conversation: str) -> str:
+    """Address a conversation by the bot it lives on and WeCom's own chat id."""
+
+    return f"{_PROVIDER_PREFIX}:{bot_id}:{conversation}"
+
+
+def parse_provider_thread_id(value: str) -> tuple[str, str]:
+    """Split a provider thread id back into the bot id and the WeCom chat id."""
+
+    if not isinstance(value, str) or not value:
+        raise ValueError("WeCom provider_thread_id must be non-empty")
+    parts = value.split(":", 2)
+    if len(parts) != 3 or parts[0] != _PROVIDER_PREFIX or not parts[1] or not parts[2]:
+        raise ValueError("WeCom provider_thread_id has invalid format")
+    return parts[1], parts[2]
+
+
+@dataclass(frozen=True, slots=True)
+class TopicAddress:
+    bot_id: str
+    topic_id: str
+    post_id: str | None = None
+
+    @property
+    def provider_thread_id(self) -> str:
+        value = (
+            f"wecom:{quote(self.bot_id, safe='')}:topic:{quote(self.topic_id, safe='')}"
+        )
+        if self.post_id is not None:
+            value += f":post:{quote(self.post_id, safe='')}"
+        return value
+
+    @classmethod
+    def parse(cls, value: str) -> TopicAddress | None:
+        parts = value.split(":")
+        if len(parts) not in {4, 6} or parts[0] != "wecom" or parts[2] != "topic":
+            return None
+        if not parts[1] or not parts[3]:
+            raise ValueError("WeCom topic address requires a bot and channel")
+        if len(parts) == 6 and (parts[4] != "post" or not parts[5]):
+            raise ValueError("WeCom topic address requires a post id")
+        return cls(
+            unquote(parts[1]),
+            unquote(parts[3]),
+            unquote(parts[5]) if len(parts) == 6 else None,
+        )
+
+
+def post_message_id(post_id: str) -> str:
+    return "post:" + quote(post_id, safe="")
+
+
+def reply_message_id(post_id: str, reply_id: str) -> str:
+    return "reply:" + quote(post_id, safe="") + ":" + quote(reply_id, safe="")
+
+
+__all__ = [
+    "TopicAddress",
+    "conversation_thread_id",
+    "parse_provider_thread_id",
+    "post_message_id",
+    "reply_message_id",
+]