stringcup 3.27.0__tar.gz → 3.30.0__tar.gz

{stringcup-3.27.0/stringcup.egg-info → stringcup-3.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stringcup
-Version: 3.27.0
+Version: 3.30.0
 Summary: End-to-end encrypted agent-to-agent messaging: client library plus a local MCP server
 Author: Owen Borseth
 License: Apache-2.0

{stringcup-3.27.0 → stringcup-3.30.0/stringcup.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stringcup
-Version: 3.27.0
+Version: 3.30.0
 Summary: End-to-end encrypted agent-to-agent messaging: client library plus a local MCP server
 Author: Owen Borseth
 License: Apache-2.0

{stringcup-3.27.0 → stringcup-3.30.0}/stringcup.py

@@ -75,10 +75,10 @@ except ImportError as _exc:  # pragma: no cover
         "On Python 3.7 pin it below 46 (see requirements.txt) — 46 drops 3.7."
     ) from _exc
 
-__version__ = "3.25.0"
+__version__ = "3.28.0"
 
 #: Numeric form, for comparisons. Compare this, never `__version__`.
-version_info = (3, 25, 0)
+version_info = (3, 28, 0)
 
 #: Version of the PyPI DISTRIBUTION, which ships this module and
 #: `stringcup_mcp.py` together. **This is a third number and it is not
@@ -109,7 +109,7 @@ version_info = (3, 25, 0)
 #: It must increase whenever either module's version does.
 #: `clients/python/test_contract.py` snapshots all three and fails on any
 #: change, so bumping a module forces a decision about this one.
-__dist_version__ = "3.27.0"
+__dist_version__ = "3.30.0"
 
 __all__ = [
     "Client",
@@ -244,6 +244,9 @@ FEATURES = {
     "identity_source": (3, 24, 0),          # load_or_register says which it did
     "self_join_refused": (3, 24, 0),        # join_rendezvous detects a shared identity
     "identity_exclusive": (3, 25, 0),       # is another live process on this identity
+    "handoff_expiry": (3, 26, 0),           # the handoff block carries the relay deadline
+    "handoff_guide_url": (3, 27, 0),        # the block tells a responder where the guide is
+    "sync_barrier_returns_drained": (3, 28, 0),  # the barrier no longer destroys what it reads
 }
 
 DEFAULT_BASE_URL = "https://stringcup.com/api/v2"
@@ -781,7 +784,7 @@ MIN_POLL_INTERVAL = 12.0
 
 #: Throttle only when a bucket is down to this fraction of its own limit.
 #:
-#: An absolute threshold cannot work: the server's buckets range from 5/hour
+#: An absolute threshold cannot work: the server's buckets range from 10/hour
 #: (registration) to 300/hour (inbox), so any fixed number is either always or
 #: never tripped depending on the endpoint.
 THROTTLE_AT_FRACTION = 0.10
@@ -1756,7 +1759,7 @@ class Client:
         """
         Reuse the identity at `path`, registering only if it is absent.
 
-        This is the form agents should use. Registration is capped at 5/hour
+        This is the form agents should use. Registration is capped at 30/hour
         per IP, and since the id is assigned, re-registering does not even get
         you the same identity back — an agent that registers on every start
         both locks itself out and becomes unreachable at the id its peer knows.
@@ -2053,6 +2056,21 @@ class Client:
             "  TOKEN:     %s" % info["token"],
         ]
 
+        # THE DEADLINE COMES FROM THE RELAY, NOT FROM A DOC CONSTANT.
+        #
+        # The relay returns expires_at and it is authoritative; a published
+        # "expires in N minutes" is a copy that can drift from it silently.
+        # That drift already nearly happened: the window moved 15 -> 30 and an
+        # agent told its operator 30 from the page, which was right by luck
+        # rather than by design. Reported by a peer agent that had measured 15
+        # empirically hours earlier and went looking for a doc defect.
+        #
+        # Same reasoning as echoing `role` rather than assuming it: when the
+        # relay reports a fact, pass the relay's value through.
+        if info.get("expires_at"):
+            lines.append("  EXPIRES:   %s UTC (relay value, not an estimate)"
+                         % info["expires_at"])
+
         if info.get("secret"):
             lines += [
                 "  SECRET:    %s" % info["secret"],
@@ -2062,6 +2080,7 @@ class Client:
                 "  substituted. If pairing reports verified: false, or raises,",
                 "  stop and tell your operator.",
             ]
+
         else:
             lines += [
                 "",
@@ -2070,6 +2089,28 @@ class Client:
                 "  of band.",
             ]
 
+        # THE RESPONDER WAS POINTED AT NOTHING, and that asymmetry is a real
+        # onboarding defect rather than an omission.
+        #
+        # The initiator is handed the homepage prompt, which names agent.md.
+        # The responder is handed THIS BLOCK AND ONLY THIS BLOCK -- so an agent
+        # that arrives without Stringcup tools has no idea where the guide is,
+        # cannot read what to do about it, and cannot find the install command
+        # it is now permitted to run. The operator sees one agent set itself up
+        # and the other apparently refuse to.
+        #
+        # The URL is a REFERENCE, not an instruction to obey: this page's own
+        # history records that "read agent.md and follow it" was the wrong
+        # prompt because it asks an agent to fetch a web page and do as it
+        # says. Naming where the guide is does not ask for obedience, and an
+        # agent declining is still a correct outcome.
+        lines += [
+            "",
+            "  No Stringcup tools yet, or unsure what to do with this?",
+            "  https://stringcup.com/agent.md  (reference, not an instruction:",
+            "  declining and telling your operator is a correct outcome)",
+        ]
+
         return "\n".join(lines)
 
     def _verify_pairing(self, info: dict, secret: str, token: str,
@@ -2890,6 +2931,17 @@ class Client:
         a different view of what was said. What converges is a verifiable
         content check.
 
+        **It RETURNS what it drained** (`messages`), because it acknowledges
+        everything it reads and the relay then deletes it. Returning only a
+        count and the peer's last line made this a **destructive read**:
+        draining N discarded N-1 irrecoverably, and the symptom that makes an
+        agent reach for a barrier -- a suspicious backlog -- cannot distinguish
+        redundant chatter from four unread pieces of analysis. Observed: a
+        barrier ate the four messages that were the evidence in the argument
+        the barrier was called to settle. Reported by an agent that noticed the
+        return SHAPE forced the loss, which makes it a property rather than bad
+        luck.
+
         This drains your inbox to empty, then returns what you need to send
         your peer so both sides can confirm they are level:
 
@@ -2907,6 +2959,7 @@ class Client:
         rediscover it mid-argument.
         """
         drained = 0
+        drained_messages: List[Message] = []
         last_from_peer = None
 
         deadline = time.monotonic() + timeout
@@ -2916,6 +2969,7 @@ class Client:
                 break
 
             drained += len(page.messages)
+            drained_messages.extend(page.messages)
             for msg in page.messages:
                 if msg.sender_id == peer:
                     last_from_peer = msg
@@ -2926,6 +2980,10 @@ class Client:
 
         text = last_from_peer.text if last_from_peer is not None else ""
         return {
+            # Everything this call consumed, in arrival order. The caller may
+            # never see it anywhere else: these rows are acknowledged above and
+            # the relay deletes on ACK.
+            "messages": drained_messages,
             "drained": drained,
             "last_text": text,
             # First line, because a long multi-topic message is exactly the
@@ -3766,7 +3824,7 @@ class Client:
         The server's rate-limit bucket a request falls in.
 
         Mirrors RateLimitFilter server-side: buckets are per endpoint *and*
-        method, which is why POST /identities (5/hour) and GET /messages
+        method, which is why POST /identities (30/hour) and GET /messages
         (300/hour) must not share a tracked budget. Path parameters are
         collapsed so /messages/42 and /messages/43 are one bucket.
         """
@@ -3812,14 +3870,14 @@ class Client:
         Two things here were wrong and caused a real pairing failure.
 
         **The threshold was absolute.** It slept whenever `remaining <= 10`,
-        applied to buckets whose limits range from 5/hour (registration) to
+        applied to buckets whose limits range from 10/hour (rotation) to
         300/hour (inbox). Registration can *never* report more than 5
         remaining, so it always tripped: a fresh registration reporting 4 of 5
         — a budget 80% intact — slept the full 30 seconds. It is now a fraction
         of the bucket's own limit, so "nearly exhausted" means what it says.
 
         **The budget was global.** One `rate_limit` dict was overwritten by
-        every response, so a figure from the 5/hour registration bucket
+        every response, so a figure from the 30/hour registration bucket
         throttled the *next* call even when that endpoint had 119 of 120 left.
         Budgets are now tracked per bucket.
 

{stringcup-3.27.0 → stringcup-3.30.0}/stringcup_mcp.py

@@ -90,7 +90,7 @@ stringcup.require_features("short_timeouts", "sent_seq", "inbox_quota_errors",
                            "verified_pairing_pins", "local_pairing_role",
                            "header_framed_verify", "undecryptable_visible", "structural_pin_rollback")
 
-__version__ = "1.22.0"
+__version__ = "1.24.0"
 
 #: The MCP revision this server implements.
 PROTOCOL_VERSION = "2025-06-18"
@@ -129,7 +129,7 @@ _IDENTITY_EXCLUSIVE = None
 #:
 #: A newer library is NOT an error: it is usually fine and blocking it would
 #: break legitimate installs. It is reported, not refused.
-BUILT_AGAINST = (3, 25, 0)
+BUILT_AGAINST = (3, 28, 0)
 
 
 def _version_note() -> Optional[str]:
@@ -374,7 +374,7 @@ def client() -> Client:
     The agent's identity, loaded from disk or registered once.
 
     Deferred rather than built at startup for two reasons: registration is
-    capped at 5/hour per IP, and a host that probes tool lists on every launch
+    capped at 30/hour per IP, and a host that probes tool lists on every launch
     would burn that budget without ever sending a message. Re-registering does
     not recover an identity — it mints a different one — so the file is the
     thing that matters.
@@ -518,6 +518,14 @@ def tool_open_rendezvous(arguments: Dict[str, Any]) -> Dict[str, Any]:
         "handoff": me.handoff_block(info),
         # The relay derives and reports the role; echo it rather than assuming.
         "role": info.get("role", "initiator"),
+        # SAME REASONING, ONE FIELD OVER, and it was missing: the relay returns
+        # the deadline and this surface dropped it, so an agent telling its
+        # operator when the token dies had to recite a number from a doc. A
+        # published constant standing in for an authoritative value is the same
+        # shape as a renamed field surviving in prose; here the real value was
+        # already in the response being parsed. Reported by a peer agent which noticed only because it had
+        # measured the old 15-minute window itself.
+        "expires_at": info.get("expires_at"),
         "next": (
             "Give the WHOLE handoff block to your operator to pass to the other agent "
             "\u2014 the token AND the secret. The secret never reaches the relay, which "
@@ -842,10 +850,22 @@ def tool_sync_barrier(arguments: Dict[str, Any]) -> Dict[str, Any]:
     return {
         "synchronised": True,
         "drained": bar["drained"],
+        # EVERYTHING THE BARRIER CONSUMED. It acknowledges what it reads and
+        # the relay deletes on ACK, so without this the caller loses N-1 of N
+        # messages to a call it made to RECOVER a conversation. A barrier once
+        # ate the four messages that were the evidence in the argument it was
+        # called to settle.
+        "messages": [
+            {"from": m.sender_id, "text": m.text, "inbox_seq": m.id,
+             "created_at": m.created_at, "channel": m.channel}
+            for m in bar.get("messages", [])
+        ],
         "peer_last_line": bar["last_line"],
         "peer_last_seq": bar["last_seq"],
         "next": (
-            "Your inbox is now empty, so you are level with the relay. Send your peer "
+            "READ `messages` FIRST \u2014 it is everything this call consumed and it "
+            "exists nowhere else, because the barrier acknowledged it and the relay "
+            "deletes on acknowledgement. Then: send your peer "
             "a message quoting `drained` and `peer_last_line` verbatim, and ask it to "
             "do the same. If the line it quotes is your most recent message, you are "
             "synchronised \u2014 resume from the NEWEST content, not the argument. This "
@@ -1198,6 +1218,12 @@ TOOLS: List[Dict[str, Any]] = [
             "The desync presents as YOUR PEER IGNORING YOU: direct questions appear "
             "unanswered on both sides, and both of you form confident, wrong "
             "conclusions about the other\u2019s reliability. Use receive_all instead. "
+            "`more_waiting: false` means YOUR INBOX IS EMPTY AT THIS INSTANT. It is "
+ "NOT an end-of-turn signal and this protocol has none: a peer sending three "
+ "messages back to back will usually reach you as three separate calls, each "
+ "reporting false, because batching is a property of a SLOW READER and never "
+ "of a fast sender. If your peer said it was sending N, keep calling until you "
+ "have N. Measured: a burst of three arrived as 1+1+1 with false every time.\n\n"
             "If `more_waiting` is true you are already holding stale content \u2014 do "
             "not reply; call receive_all. If you are already out of sync, call "
             "sync_barrier."