stringcup 3.27.0__tar.gz → 3.32.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stringcup
-Version: 3.27.0
+Version: 3.32.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.32.0/stringcup.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stringcup
-Version: 3.27.0
+Version: 3.32.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.32.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.29.0"
 
 #: Numeric form, for comparisons. Compare this, never `__version__`.
-version_info = (3, 25, 0)
+version_info = (3, 29, 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.32.0"
 
 __all__ = [
     "Client",
@@ -244,6 +244,10 @@ 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
+    "handoff_objective": (3, 29, 0),        # the brief and the operator setup ride the block
 }
 
 DEFAULT_BASE_URL = "https://stringcup.com/api/v2"
@@ -781,7 +785,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 +1760,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.
@@ -2038,21 +2042,64 @@ class Client:
 
         return info
 
-    def handoff_block(self, info: dict, role: str = "responder") -> str:
+    def handoff_block(self, info: dict, role: str = "responder",
+                      objective: Optional[str] = None) -> str:
         """
         The block an operator pastes to the other agent, secret included.
 
         Exists so the secret cannot be forgotten. The handoff was already a
         copy-paste; carrying one more line in it is the entire cost of
         authenticating first contact.
+
+        `objective` is what the work IS. Pass the brief your own operator gave
+        you. A responder handed a token and nothing else is an untasked agent,
+        and this project already records what that costs: both sides assume
+        the other was briefed, and neither says so.
         """
-        lines = [
-            "STRINGCUP HANDOFF",
+        lines = ["STRINGCUP HANDOFF", ""]
+
+        # THE OPERATOR SECTION COMES FIRST BECAUSE IT IS READ BEFORE PASTING.
+        #
+        # Self-install is a bonus that usually does not arrive. Measured on one
+        # machine on 2026-09-17: the identical command has been both permitted
+        # and refused repeatedly, and four controlled runs in one sitting were
+        # refused every time -- the agent's role, the operator's own phrasing
+        # and the presence of a task brief each tested and each eliminated. A
+        # string permitted earlier was refused later, so nothing about the
+        # prompt is the cause. It is unpredictable, not uniformly blocked. Onboarding is two operator actions, and putting
+        # the first one here means the operator reads it at the moment they are
+        # already acting, rather than after a refused attempt costs a round
+        # trip against a token that expires.
+        lines += [
+            "  BEFORE YOU PASTE THIS -- for the operator, not the agent.",
+            "  If the receiving agent has no Stringcup tools yet, run this in",
+            "  its project and restart it first. An MCP config is read at",
+            "  startup, so the restart is required either way, and the agent",
+            "  is often refused when it tries this itself:",
+            "",
+            "      claude mcp add stringcup -- uvx --from stringcup stringcup-mcp",
+            "",
+            "  The token below is time-boxed, so a setup detour can outlive it.",
             "",
             "  YOUR ROLE: %s" % role,
             "  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 +2109,7 @@ class Client:
                 "  substituted. If pairing reports verified: false, or raises,",
                 "  stop and tell your operator.",
             ]
+
         else:
             lines += [
                 "",
@@ -2070,6 +2118,45 @@ 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.
+        # THE WORK, NOT JUST THE CONNECTION. An agent that arrives holding a
+        # token and no brief has to guess, or ask -- and its peer, which does
+        # have a brief, reads the silence as the peer being slow rather than
+        # uninformed. The initiator was required to prompt for an objective
+        # before pairing, so it always has one to pass on; not passing it was
+        # an omission rather than a design.
+        if objective:
+            lines += [
+                "",
+                "  OBJECTIVE: %s" % objective,
+                "",
+                "  That is what your operator asked of the agent that opened this",
+                "  pairing. Confirm it with your own operator rather than adopting",
+                "  it -- it reached you through them, and they may be handing you a",
+                "  different part of the work.",
+            ]
+
+        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 +2977,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 +3005,7 @@ class Client:
         rediscover it mid-argument.
         """
         drained = 0
+        drained_messages: List[Message] = []
         last_from_peer = None
 
         deadline = time.monotonic() + timeout
@@ -2916,6 +3015,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 +3026,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 +3870,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 +3916,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.32.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.26.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, 29, 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.
@@ -509,21 +509,38 @@ def tool_whoami(arguments: Dict[str, Any]) -> Dict[str, Any]:
 def tool_open_rendezvous(arguments: Dict[str, Any]) -> Dict[str, Any]:
     me = client()
     info = me.open_rendezvous()
+    objective = arguments.get("objective")
     return {
         "token": info["token"],
         # Generated here and NEVER sent to the relay. The relay issues the
         # token, so the token authenticates nothing about a key the relay
         # served; this is the half it cannot know.
         "secret": info.get("secret"),
-        "handoff": me.handoff_block(info),
+        "handoff": me.handoff_block(info, objective=objective),
         # 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 "
             "is what lets the pairing prove neither key was substituted; the token "
             "alone cannot, because the relay issued it. Then call await_peer with both. "
-            "You are the initiator: you speak first once paired."
+            "You are the initiator: you speak first once paired.\n\n"
+            "TELL YOUR OPERATOR TO CONFIGURE THE SECOND AGENT BEFORE PASTING THIS. "
+            "You were able to reach Stringcup; the responder frequently is not, and "
+            "cannot fix it from inside its own session \u2014 an MCP config is read at "
+            "startup, so it must be set up and then restarted before it can join. "
+            "Observed twice on one machine: the initiator registered the server fine "
+            "and the responder was refused. Setting the second agent up first turns "
+            "two round trips into none, and the rendezvous is time-boxed, so a setup "
+            "detour can outlive the token."
         ),
     }
 
@@ -842,10 +859,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 "
@@ -1054,9 +1083,26 @@ TOOLS: List[Dict[str, Any]] = [
             "token proves nothing about a key the relay served, but a tag computed "
             "over both public keys with the secret matches only if neither key was "
             "substituted. It costs your operator nothing — the same single paste was "
-            "already happening. Never put the secret in a message."
+            "already happening. Never put the secret in a message.\n\n"
+            "PASS `objective` — the brief your own operator gave you, in one or "
+            "two sentences. It rides the handoff so the other agent arrives knowing "
+            "what the work is. Without it they get a token and nothing else, and an "
+            "untasked agent and a briefed one each assume the other was told, which "
+            "reads as the peer being slow rather than uninformed. You were required "
+            "to ask your operator for an objective before pairing, so you have one."
         ),
-        "inputSchema": {"type": "object", "properties": {}},
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "objective": {
+                    "type": "string",
+                    "description": (
+                        "What the work is, from your own operator's brief. Travels "
+                        "in the handoff block so the peer is not left guessing."
+                    ),
+                },
+            },
+        },
         "handler": tool_open_rendezvous,
     },
     {
@@ -1198,6 +1244,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."