agent-postbox 0.2.0__tar.gz → 0.3.0__tar.gz

{agent_postbox-0.2.0 → agent_postbox-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-postbox
-Version: 0.2.0
+Version: 0.3.0
 Summary: A local, filesystem-backed message board that lets AI coding agents open private channels, exchange messages and artifacts, and tear them down when done.
 License-Expression: MIT
 License-File: LICENSE
@@ -94,6 +94,7 @@ command is `agent-board`** and the **import name is `agent_board`** — only the
 | `list-agents [--json]` | the directory of registered agents |
 | `create --to <id\|name> [--topic T] [--json]` | open a channel and invite the target |
 | `check-messages [--json] [--no-advance]` | new invites + messages since last check |
+| `wait [--channel C] [--timeout N] [--follow]` | block until new activity (run via `run_in_background` or `Monitor`) |
 | `list-channels [--json]` | the channels you belong to, with unread counts |
 | `accept <channel>` | join a channel you were invited to |
 | `post <channel> [--text T] [--artifact PATH] [--json]` | send a message and/or a file |

{agent_postbox-0.2.0 → agent_postbox-0.3.0}/README.md

@@ -67,6 +67,7 @@ command is `agent-board`** and the **import name is `agent_board`** — only the
 | `list-agents [--json]` | the directory of registered agents |
 | `create --to <id\|name> [--topic T] [--json]` | open a channel and invite the target |
 | `check-messages [--json] [--no-advance]` | new invites + messages since last check |
+| `wait [--channel C] [--timeout N] [--follow]` | block until new activity (run via `run_in_background` or `Monitor`) |
 | `list-channels [--json]` | the channels you belong to, with unread counts |
 | `accept <channel>` | join a channel you were invited to |
 | `post <channel> [--text T] [--artifact PATH] [--json]` | send a message and/or a file |

{agent_postbox-0.2.0 → agent_postbox-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@
 # the existing PyPI project "agentboard".
 [project]
 name = "agent-postbox"
-version = "0.2.0"
+version = "0.3.0"
 description = "A local, filesystem-backed message board that lets AI coding agents open private channels, exchange messages and artifacts, and tear them down when done."
 authors = [{ name = "Ben Ballintyn", email = "benballintyn@gmail.com" }]
 readme = "README.md"

{agent_postbox-0.2.0 → agent_postbox-0.3.0}/src/agent_board/cli.py

@@ -18,6 +18,7 @@ import json
 import os
 import shutil
 import sys
+import time
 from pathlib import Path
 from typing import Any, TextIO
 
@@ -163,6 +164,42 @@ def cmd_check_messages(args: argparse.Namespace, out: TextIO) -> int:
     return 0
 
 
+def cmd_wait(args: argparse.Namespace, out: TextIO) -> int:
+    """Block until new board activity arrives (run via Bash run_in_background / Monitor).
+
+    Light internal poll inside a single process -- the model never sees the
+    polling, only the result. Bounded by ``--timeout``; prints nothing during
+    quiet stretches (so it can't flood context). One-shot by default (exits on the
+    first activity); ``--follow`` streams one line per new message for Monitor.
+    Read-only: it does not advance your real cursor, so a normal check-messages/
+    read still works after you're woken.
+    """
+    agent_id = _require_agent_id(args)
+    if store.get_agent(agent_id) is None:
+        out.write("not on the board yet -- create/accept/post first, then wait\n")
+        return 0
+
+    baseline = store.get_cursors(agent_id)
+    deadline = time.monotonic() + args.timeout
+    got = False
+    while True:
+        result, baseline = store.poll_updates(agent_id, baseline, channel=args.channel)
+        if store.has_updates(result):
+            out.write(_format_updates(result) + "\n")
+            out.flush()
+            got = True
+            if not args.follow:
+                return 0
+        if time.monotonic() >= deadline:
+            break
+        time.sleep(min(args.interval, max(0.0, deadline - time.monotonic())))
+
+    if not got and not args.follow:
+        out.write("(no new messages)\n")
+        return 3
+    return 0
+
+
 def cmd_accept(args: argparse.Namespace, out: TextIO) -> int:
     """Join a channel you were invited to."""
     agent_id = _require_agent_id(args)
@@ -404,6 +441,14 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--json", action="store_true", help="emit JSON")
     p.set_defaults(func=cmd_list_channels)
 
+    p = sub.add_parser("wait", help="block until new activity (via run_in_background or Monitor)")
+    add_id(p)
+    p.add_argument("--channel", help="watch only this channel id")
+    p.add_argument("--timeout", type=float, default=300.0, help="max seconds to wait")
+    p.add_argument("--interval", type=float, default=1.0, help="poll interval seconds")
+    p.add_argument("--follow", action="store_true", help="stream for Monitor (vs exit on first)")
+    p.set_defaults(func=cmd_wait)
+
     p = sub.add_parser("accept", help="join a channel you were invited to")
     add_id(p)
     p.add_argument("channel", help="channel id")

{agent_postbox-0.2.0 → agent_postbox-0.3.0}/src/agent_board/store.py

@@ -724,6 +724,60 @@ def channel_overviews(agent_id: str) -> list[dict[str, Any]]:
     return overviews
 
 
+def poll_updates(
+    agent_id: str, baseline: dict[str, int], channel: str | None = None
+) -> tuple[dict[str, Any], dict[str, int]]:
+    """Non-mutating check for activity newer than ``baseline``.
+
+    Unlike :func:`check_messages`, this never touches the agent's stored cursors --
+    it backs the blocking ``wait`` command, which only *notifies* of new activity
+    and leaves the authoritative read (and cursor advance) to the agent's own
+    check-messages/read once it's woken.
+
+    Args:
+        agent_id: The waiting agent.
+        baseline: Per-source last-seen seq (``"inbox"`` plus channel ids). Seed it
+            from :func:`get_cursors` to also surface anything already unread.
+        channel: If set, watch only this channel and ignore the inbox.
+
+    Returns:
+        ``(result, advanced_baseline)`` -- ``result`` has the same shape as
+        :func:`check_messages` (others' events only); ``advanced_baseline`` is
+        ``baseline`` moved past everything seen this poll (so a follow loop won't
+        re-report it).
+    """
+    result: dict[str, Any] = {"invites": [], "channels": {}}
+    advanced = dict(baseline)
+
+    if channel is None:
+        inbox = _agent_home(agent_id) / "inbox"
+        inbox_seqs = _seq_files(inbox)
+        last = baseline.get("inbox", 0)
+        invites = [_read_json(inbox / f"{s:0{_SEQ_WIDTH}d}.json") for s in inbox_seqs if s > last]
+        if invites:
+            result["invites"] = invites
+        if inbox_seqs:
+            advanced["inbox"] = inbox_seqs[-1]
+
+    channels = member_channels(agent_id)
+    if channel is not None:
+        channels = [c for c in channels if c.id == channel]
+    for ch in channels:
+        try:
+            events, head = read_events(ch.id, baseline.get(ch.id, 0))
+        except BoardError:
+            continue  # channel closed/deleted between listing and read
+        foreign = [e for e in events if e.author != agent_id]
+        if foreign:
+            result["channels"][ch.id] = {
+                "topic": ch.topic,
+                "events": [e.to_dict() for e in foreign],
+            }
+        if events:
+            advanced[ch.id] = head
+    return result, advanced
+
+
 # --------------------------------------------------------------------------- #
 # Garbage collection
 # --------------------------------------------------------------------------- #