agent-party 0.2.0__py3-none-any.whl

agent_party/__init__.py

@@ -0,0 +1,36 @@
+# Chunk: docs/chunks/foundation_scaffold - Project skeleton and shared primitives
+"""agent-party: ephemeral, end-to-end encrypted chat rooms for autonomous agents.
+
+The three modules exported here are the cross-cutting primitives every other
+part of the system agrees on: the injected clock, the error taxonomy, and
+identifier derivation. Domain behavior lives in the subpackages.
+"""
+
+from agent_party.clock import Clock, ManualClock, SystemClock
+from agent_party.errors import AgentChatError, ErrorCode
+from agent_party.ids import (
+    derive_participant_id,
+    new_link_id,
+    new_org_id,
+    new_room_id,
+)
+
+__all__ = [
+    "AgentChatError",
+    "Clock",
+    "ErrorCode",
+    "ManualClock",
+    "SystemClock",
+    "derive_participant_id",
+    "new_link_id",
+    "new_org_id",
+    "new_room_id",
+]
+
+__version__ = "0.2.0"
+
+#: The User-Agent every client transport sends. A request with no User-Agent, or
+#: the default `Python-urllib/x`, is blocked at Cloudflare's edge (error 1010,
+#: "banned by browser signature") before it ever reaches the deployed Worker, so
+#: naming ourselves is what lets the client talk to the hosted service at all.
+USER_AGENT = f"agent-party/{__version__}"

agent_party/__main__.py

@@ -0,0 +1,11 @@
+# Chunk: docs/chunks/foundation_scaffold - Project skeleton and shared primitives
+"""Make the CLI reachable as `python -m agent_party`.
+
+The console script is the product surface; this exists so tests can exercise
+the entry point without depending on where the script landed on PATH.
+"""
+
+from agent_party.cli import main
+
+if __name__ == "__main__":
+    main()

agent_party/adapters/__init__.py

@@ -0,0 +1,7 @@
+# Chunk: docs/chunks/foundation_scaffold - Reserved by the scaffold
+"""Host adapters that put the portable core behind a real transport.
+
+One adapter per host. `local/` is the fast test target; the Cloudflare Workers
+adapter lives in `workers/agent-chat/` because it is TypeScript. Both answer to
+the same conformance suite (DEC-008).
+"""

agent_party/adapters/local/__init__.py

@@ -0,0 +1,8 @@
+# Chunk: docs/chunks/foundation_scaffold - Reserved by the scaffold
+"""The local server adapter.
+
+Owned by `docs/chunks/room_local_server`: WebSocket with the challenge-attach
+handshake, the HTTP blocking read that drains everything past a cursor, session
+tokens, and filesystem-backed durable storage. This is the fast target the
+conformance suite runs against.
+"""

agent_party/adapters/local/fs_storage.py

@@ -0,0 +1,504 @@
+# Chunk: docs/chunks/room_local_server - Local server adapter: filesystem storage
+"""Filesystem-backed `RoomStorage`.
+
+The durable half of the local adapter. `src/agent_party/core/storage.py` states
+the contract and `tests/unit/room_core_storage_contract.py` asserts it; this
+module supplies a `tmp_path`-shaped root and passes that suite with a four-line
+subclass and no new tests.
+
+Layout under the configured root::
+
+    <root>/rooms/<room_id>/
+        room.json                       the Room record
+        meta.json                       {"head": N, "bytes": B}
+        messages.jsonl                  one JSON object per line, append-only
+        participants/<participant_id>.json
+        .lock                           flock target for position assignment
+
+Three obligations are the ones an adapter gets wrong, so each is answered here
+in the same order `storage.py` states them.
+
+**Positions are assigned atomically.** Reading the head, writing the message
+line, and writing the new head all happen under an exclusive `fcntl.flock` on
+`.lock`, and the whole locked region is synchronous — there is no `await`
+between the read and the write, so no interleaving can occur inside it. The
+locked region runs in `asyncio.to_thread`, which means this adapter *genuinely
+suspends* between concurrent appends. That matters more than it looks:
+`tests/unit/test_room_core_memory_storage.py` observes that the in-memory
+adapter has no suspension point anywhere, so the contract's concurrency test
+passes against it without ever exercising the property it names. Against this
+adapter the interleaving is real and `flock` is what the test actually proves.
+
+The lock is POSIX advisory locking, which attaches to the *open file
+description* rather than to the process, so two `open()` calls in one process —
+one per worker thread — do contend. It is still advisory and still
+filesystem-dependent: over NFS it is not a guarantee. This adapter is a
+development and conformance target, not a deployment.
+
+**No clock is read.** `sent_at` arrives as an argument, from the core's injected
+clock. There is no `datetime.now` in this module, deliberately: an adapter that
+stamped its own time would put a wall clock under a suite that must not have
+one.
+
+**No derived state is stored.** A participant is a whole row with no `state`
+column; `Participant.state(now, live_participant_ids)` derives it at read time
+(DEC-011). `put_participant` is a whole-row replace, written to a temporary file
+and `os.replace`d, so a concurrent reader sees the old row or the new one and
+never half of either.
+
+Identifiers become path segments, so every one is checked with `is_valid_id`
+before it is joined to the root. A malformed identifier yields the empty answer
+on a read path and raises on a write path; nothing can traverse out of the root.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import fcntl
+import json
+import os
+import shutil
+from collections.abc import Callable
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from agent_party.core.models import (
+    CloseReason,
+    LivenessMode,
+    Participant,
+    Room,
+    StoredMessage,
+)
+from agent_party.ids import is_valid_id
+
+__all__ = ["FileSystemRoomStorage"]
+
+_ROOMS = "rooms"
+_ROOM_RECORD = "room.json"
+_META = "meta.json"
+_MESSAGES = "messages.jsonl"
+_PARTICIPANTS = "participants"
+_LOCK = ".lock"
+
+#: `meta.json` keys. The head and the byte total are maintained together under
+#: the append lock so they can never disagree about what the log contains.
+_HEAD = "head"
+_BYTES = "bytes"
+
+
+class FileSystemRoomStorage:
+    """A durable `RoomStorage` over a directory tree."""
+
+    __slots__ = ("_root",)
+
+    def __init__(self, root: Path | str) -> None:
+        self._root = Path(root)
+        (self._root / _ROOMS).mkdir(parents=True, exist_ok=True)
+
+    @property
+    def root(self) -> Path:
+        """The directory this adapter owns.
+
+        Public because reclamation is verified by inspecting storage rather
+        than by asking the API (`docs/trunk/TESTING_PHILOSOPHY.md`), and a test
+        that cannot see the bytes cannot make that assertion.
+        """
+        return self._root
+
+    # --- Paths -------------------------------------------------------------
+
+    def _room_dir(self, room_id: str) -> Path | None:
+        """The room's directory, or `None` if `room_id` is not an identifier.
+
+        Returning `None` rather than raising is what lets every read path answer
+        "nothing here" for a malformed identifier, which is the same answer it
+        gives for one that is well-formed and absent. Write paths turn the
+        `None` into a `ValueError`.
+        """
+        if not is_valid_id(room_id):
+            return None
+        return self._root / _ROOMS / room_id
+
+    def _require_room_dir(self, room_id: str) -> Path:
+        directory = self._room_dir(room_id)
+        if directory is None:
+            raise ValueError(f"not a well-formed room_id: {room_id!r}")
+        return directory
+
+    @staticmethod
+    def _participant_path(room_dir: Path, participant_id: str) -> Path | None:
+        if not is_valid_id(participant_id):
+            return None
+        return room_dir / _PARTICIPANTS / f"{participant_id}.json"
+
+    # --- Rooms -------------------------------------------------------------
+
+    async def create_room(self, room: Room) -> None:
+        await _in_thread(self._create_room, room)
+
+    def _create_room(self, room: Room) -> None:
+        directory = self._require_room_dir(room.room_id)
+        if (directory / _ROOM_RECORD).exists():
+            raise ValueError(f"room already exists: {room.room_id}")
+        (directory / _PARTICIPANTS).mkdir(parents=True, exist_ok=True)
+        _write_atomic(directory / _META, json.dumps({_HEAD: 0, _BYTES: 0}))
+        (directory / _MESSAGES).touch(exist_ok=True)
+        (directory / _LOCK).touch(exist_ok=True)
+        _write_atomic(directory / _ROOM_RECORD, json.dumps(_room_to_json(room)))
+
+    async def get_room(self, room_id: str) -> Room | None:
+        return await _in_thread(self._get_room, room_id)
+
+    def _get_room(self, room_id: str) -> Room | None:
+        directory = self._room_dir(room_id)
+        if directory is None:
+            return None
+        raw = _read_text(directory / _ROOM_RECORD)
+        return None if raw is None else _room_from_json(json.loads(raw))
+
+    async def put_room(self, room: Room) -> None:
+        await _in_thread(self._put_room, room)
+
+    def _put_room(self, room: Room) -> None:
+        directory = self._require_room_dir(room.room_id)
+        if not (directory / _ROOM_RECORD).exists():
+            raise ValueError(f"room does not exist: {room.room_id}")
+        _write_atomic(directory / _ROOM_RECORD, json.dumps(_room_to_json(room)))
+
+    async def delete_room(self, room_id: str) -> None:
+        await _in_thread(self._delete_room, room_id)
+
+    def _delete_room(self, room_id: str) -> None:
+        # Everything the room owns is under one directory, so destruction is one
+        # `rmtree` rather than a per-key sweep — and it is idempotent, because
+        # SPEC gives a room three independent ways to die (DEC-002).
+        directory = self._room_dir(room_id)
+        if directory is not None:
+            shutil.rmtree(directory, ignore_errors=True)
+
+    # --- The log -----------------------------------------------------------
+
+    async def head(self, room_id: str) -> int:
+        return await _in_thread(lambda: int(self._meta(room_id)[_HEAD]))
+
+    async def stored_bytes(self, room_id: str) -> int:
+        return await _in_thread(lambda: int(self._meta(room_id)[_BYTES]))
+
+    def _meta(self, room_id: str) -> dict[str, int]:
+        directory = self._room_dir(room_id)
+        if directory is None:
+            return {_HEAD: 0, _BYTES: 0}
+        raw = _read_text(directory / _META)
+        if raw is None:
+            return {_HEAD: 0, _BYTES: 0}
+        meta = json.loads(raw)
+        return {_HEAD: int(meta[_HEAD]), _BYTES: int(meta[_BYTES])}
+
+    async def append_message(
+        self, room_id: str, sender: str, sent_at: datetime, body: bytes
+    ) -> StoredMessage:
+        return await _in_thread(
+            self._append_message, room_id, sender, sent_at, bytes(body)
+        )
+
+    def _append_message(
+        self, room_id: str, sender: str, sent_at: datetime, body: bytes
+    ) -> StoredMessage:
+        directory = self._require_room_dir(room_id)
+        lock_path = directory / _LOCK
+        if not lock_path.exists():
+            raise ValueError(f"room does not exist: {room_id}")
+
+        # Everything between here and the unlock is synchronous. The position is
+        # read, used, and written back without any opportunity for another
+        # thread or another process to observe it half-assigned.
+        with open(lock_path) as lock_file:
+            fcntl.flock(lock_file, fcntl.LOCK_EX)
+            try:
+                meta = self._meta(room_id)
+                message = StoredMessage(
+                    room_id=room_id,
+                    position=meta[_HEAD] + 1,
+                    sender=sender,
+                    sent_at=sent_at,
+                    body=body,
+                )
+                with open(directory / _MESSAGES, "a", encoding="utf-8") as log:
+                    log.write(json.dumps(_message_to_json(message)) + "\n")
+                    log.flush()
+                    os.fsync(log.fileno())
+                _write_atomic(
+                    directory / _META,
+                    json.dumps(
+                        {
+                            _HEAD: message.position,
+                            _BYTES: meta[_BYTES] + message.byte_size,
+                        }
+                    ),
+                )
+                return message
+            finally:
+                fcntl.flock(lock_file, fcntl.LOCK_UN)
+
+    async def read_after(
+        self, room_id: str, cursor: int, limit: int | None = None
+    ) -> list[StoredMessage]:
+        return await _in_thread(self._read_after, room_id, cursor, limit)
+
+    def _read_after(
+        self, room_id: str, cursor: int, limit: int | None
+    ) -> list[StoredMessage]:
+        directory = self._room_dir(room_id)
+        if directory is None:
+            return []
+        path = directory / _MESSAGES
+        if not path.exists():
+            return []
+        if limit is not None and limit <= 0:
+            return []
+
+        found: list[StoredMessage] = []
+        # Chunk: docs/chunks/organization_api - a reader racing a destruction
+        #
+        # The `exists` check above and this `open` are two syscalls with a
+        # thread hop's worth of gap between them, and `delete_room` can land in
+        # it: an explicit close disconnects a socket whose delivery loop already
+        # has a read in flight. A room whose bytes are gone has no messages —
+        # which is exactly what the `directory is None` branch above already
+        # says — so the disappearance is that answer arriving late, not an
+        # error. Raising here would surface as an untyped `FileNotFoundError`
+        # out of the socket handler, where the `closing` frame has already been
+        # delivered and there is nothing left to report.
+        try:
+            log = open(path, encoding="utf-8")
+        except FileNotFoundError:
+            return []
+        with log:
+            for line in log:
+                line = line.strip()
+                if not line:
+                    continue
+                # Filtering on the recorded position rather than slicing by line
+                # index: the identity "line i holds position i + 1" is true
+                # because rooms never trim, but relying on it would make a
+                # partially written trailing line silently shift every position.
+                record = json.loads(line)
+                if record["position"] <= cursor:
+                    continue
+                found.append(_message_from_json(record))
+                if limit is not None and len(found) >= limit:
+                    break
+        return found
+
+    # --- The participant table ---------------------------------------------
+
+    async def put_participant(self, participant: Participant) -> None:
+        await _in_thread(self._put_participant, participant)
+
+    def _put_participant(self, participant: Participant) -> None:
+        directory = self._require_room_dir(participant.room_id)
+        if not (directory / _ROOM_RECORD).exists():
+            raise ValueError(f"room does not exist: {participant.room_id}")
+        path = self._participant_path(directory, participant.participant_id)
+        if path is None:
+            raise ValueError(
+                f"not a well-formed participant_id: {participant.participant_id!r}"
+            )
+        path.parent.mkdir(parents=True, exist_ok=True)
+        # A whole-row replace, written through a temporary file: a reader either
+        # sees the row that was there before or the one being written, never a
+        # truncated row.
+        _write_atomic(path, json.dumps(_participant_to_json(participant)))
+
+    async def get_participant(
+        self, room_id: str, participant_id: str
+    ) -> Participant | None:
+        return await _in_thread(self._get_participant, room_id, participant_id)
+
+    def _get_participant(self, room_id: str, participant_id: str) -> Participant | None:
+        directory = self._room_dir(room_id)
+        if directory is None:
+            return None
+        path = self._participant_path(directory, participant_id)
+        if path is None:
+            return None
+        raw = _read_text(path)
+        return None if raw is None else _participant_from_json(json.loads(raw))
+
+    async def list_participants(self, room_id: str) -> list[Participant]:
+        return await _in_thread(self._list_participants, room_id)
+
+    def _list_participants(self, room_id: str) -> list[Participant]:
+        directory = self._room_dir(room_id)
+        if directory is None:
+            return []
+        table = directory / _PARTICIPANTS
+        if not table.is_dir():
+            return []
+        rows: list[Participant] = []
+        # The same race `_read_after` documents above, one directory up:
+        # `is_dir` and `iterdir` are two syscalls and `delete_room` can land
+        # between them. A roster read racing a reclamation is the ordinary case
+        # rather than an exotic one — `broadcast_roster` runs on every presence
+        # change, and reclamation destroys storage under whatever is in flight.
+        # The individual row reads below are already guarded by `_read_text`;
+        # this is the enumeration that reaches them.
+        try:
+            entries = list(table.iterdir())
+        except FileNotFoundError:
+            return []
+        for path in entries:
+            if path.suffix != ".json":
+                continue
+            raw = _read_text(path)
+            if raw is not None:
+                rows.append(_participant_from_json(json.loads(raw)))
+        # A total, stable order: joined_at, then participant_id for ties. A
+        # roster whose order wobbles between two reads that saw no change is a
+        # roster that publishes spurious updates.
+        return sorted(rows, key=lambda row: (row.joined_at, row.participant_id))
+
+
+# --- Encoding ---------------------------------------------------------------
+#
+# Everything durable goes through these six functions. They are deliberately
+# explicit rather than reflective over the dataclasses: the on-disk shape is a
+# format, and a format that changes whenever a field is renamed is not one.
+
+
+def _room_to_json(room: Room) -> dict[str, Any]:
+    return {
+        "room_id": room.room_id,
+        "org_id": room.org_id,
+        "created_at": room.created_at.isoformat(),
+        "ttl": room.ttl.total_seconds(),
+        "idle_timeout": room.idle_timeout.total_seconds(),
+        "max_participants": room.max_participants,
+        "max_bytes": room.max_bytes,
+        "max_message_bytes": room.max_message_bytes,
+        "last_activity_at": _instant_to_json(room.last_activity_at),
+        "closed_at": _instant_to_json(room.closed_at),
+        "close_reason": None if room.close_reason is None else room.close_reason.value,
+    }
+
+
+def _room_from_json(record: dict[str, Any]) -> Room:
+    return Room(
+        room_id=record["room_id"],
+        org_id=record["org_id"],
+        created_at=datetime.fromisoformat(record["created_at"]),
+        ttl=timedelta(seconds=record["ttl"]),
+        idle_timeout=timedelta(seconds=record["idle_timeout"]),
+        max_participants=record["max_participants"],
+        max_bytes=record["max_bytes"],
+        max_message_bytes=record["max_message_bytes"],
+        last_activity_at=_instant_from_json(record["last_activity_at"]),
+        closed_at=_instant_from_json(record["closed_at"]),
+        close_reason=(
+            None
+            if record["close_reason"] is None
+            else CloseReason(record["close_reason"])
+        ),
+    )
+
+
+def _participant_to_json(participant: Participant) -> dict[str, Any]:
+    return {
+        "room_id": participant.room_id,
+        "participant_id": participant.participant_id,
+        "public_key": participant.public_key.hex(),
+        "mode": participant.mode.value,
+        "joined_at": participant.joined_at.isoformat(),
+        "link_id": participant.link_id,
+        "lease_expires_at": _instant_to_json(participant.lease_expires_at),
+        "cursor": participant.cursor,
+        "evicted_at": _instant_to_json(participant.evicted_at),
+        "departed_at": _instant_to_json(participant.departed_at),
+    }
+
+
+def _participant_from_json(record: dict[str, Any]) -> Participant:
+    return Participant(
+        room_id=record["room_id"],
+        participant_id=record["participant_id"],
+        public_key=bytes.fromhex(record["public_key"]),
+        mode=LivenessMode(record["mode"]),
+        joined_at=datetime.fromisoformat(record["joined_at"]),
+        link_id=record["link_id"],
+        lease_expires_at=_instant_from_json(record["lease_expires_at"]),
+        cursor=record["cursor"],
+        evicted_at=_instant_from_json(record["evicted_at"]),
+        departed_at=_instant_from_json(record["departed_at"]),
+    )
+
+
+def _message_to_json(message: StoredMessage) -> dict[str, Any]:
+    return {
+        "room_id": message.room_id,
+        "position": message.position,
+        "sender": message.sender,
+        "sent_at": message.sent_at.isoformat(),
+        # base64 rather than hex, and never `decode`: the body is opaque bytes
+        # that are `nonce || ciphertext` in production and arbitrary in tests,
+        # including sequences that are not valid UTF-8.
+        "body": base64.b64encode(message.body).decode("ascii"),
+    }
+
+
+def _message_from_json(record: dict[str, Any]) -> StoredMessage:
+    return StoredMessage(
+        room_id=record["room_id"],
+        position=record["position"],
+        sender=record["sender"],
+        sent_at=datetime.fromisoformat(record["sent_at"]),
+        body=base64.b64decode(record["body"]),
+    )
+
+
+def _instant_to_json(instant: datetime | None) -> str | None:
+    return None if instant is None else instant.isoformat()
+
+
+def _instant_from_json(raw: str | None) -> datetime | None:
+    return None if raw is None else datetime.fromisoformat(raw)
+
+
+# --- Filesystem helpers -----------------------------------------------------
+
+
+def _read_text(path: Path) -> str | None:
+    try:
+        return path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+
+
+def _write_atomic(path: Path, text: str) -> None:
+    """Write `text` to `path` through a temporary file in the same directory.
+
+    `os.replace` is atomic within a filesystem, so a reader observes the old
+    contents or the new ones. A plain `write_text` would let a reader see a
+    truncated record — which for `meta.json` means a lost head.
+    """
+    temporary = path.with_name(f"{path.name}.{os.getpid()}.{id(text):x}.tmp")
+    try:
+        with open(temporary, "w", encoding="utf-8") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    except BaseException:
+        temporary.unlink(missing_ok=True)
+        raise
+
+
+async def _in_thread[T](work: Callable[..., T], *args: Any) -> T:
+    """Run blocking filesystem work off the event loop.
+
+    Every method routes through here, which is what makes this adapter suspend
+    where a durable adapter really does — see the module docstring on why that
+    matters to the storage contract's concurrency test.
+    """
+    return await asyncio.to_thread(work, *args)