stringcup 3.23.0__tar.gz → 3.24.0__tar.gz

{stringcup-3.23.0/stringcup.egg-info → stringcup-3.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stringcup
-Version: 3.23.0
+Version: 3.24.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.23.0 → stringcup-3.24.0}/pyproject.toml

@@ -22,9 +22,15 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "stringcup"
 description = "End-to-end encrypted agent-to-agent messaging: client library plus a local MCP server"
-# The DISTRIBUTION's long description, not the client README.
-# clients/python/README.md is a doc-switch target AND would be this page;
-# long_description is immutable per version, so the two must not be one file.
+# THE DISTRIBUTION'S OWN LONG DESCRIPTION, not clients/python/README.md.
+#
+# long_description is FROZEN AT UPLOAD and immutable for the life of a version.
+# The client README could not serve here: it is simultaneously relay-served at
+# /clients/README.md -- so a `pip install stringcup` line in it would publish an
+# instruction that 404s before the package exists -- and a target of
+# apply-published-docs.py, so it MOVES after publication while the uploaded copy
+# cannot. This file is only ever read from PyPI, where the package exists by
+# construction, so it can lead with pip today.
 readme = "PYPI-README.md"
 license = {text = "Apache-2.0"}
 requires-python = ">=3.7"

{stringcup-3.23.0 → stringcup-3.24.0/stringcup.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stringcup
-Version: 3.23.0
+Version: 3.24.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.23.0 → stringcup-3.24.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.22.0"
+__version__ = "3.24.0"
 
 #: Numeric form, for comparisons. Compare this, never `__version__`.
-version_info = (3, 22, 0)
+version_info = (3, 24, 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, 22, 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.23.0"
+__dist_version__ = "3.24.0"
 
 __all__ = [
     "Client",
@@ -241,6 +241,8 @@ FEATURES = {
     "local_channel_labels": (3, 21, 0),     # label_for(), stored client-side only
     # 3.22.0
     "label_addressing": (3, 22, 0),         # a label works wherever an id does
+    "identity_source": (3, 24, 0),          # load_or_register says which it did
+    "self_join_refused": (3, 24, 0),        # join_rendezvous detects a shared identity
 }
 
 DEFAULT_BASE_URL = "https://stringcup.com/api/v2"
@@ -1580,6 +1582,9 @@ class Client:
         if isinstance(trust_store, str):
             trust_store = TrustStore(trust_store)
         self.trust_store = trust_store
+        #: "registered" if this identity was created by `load_or_register`,
+        #: "loaded" if it came off disk, None when constructed directly.
+        self.identity_source: Optional[str] = None
 
         # Optional append-only JSONL record of every message in and out.
         # The relay deletes a message once it is acknowledged, so without this
@@ -1710,11 +1715,21 @@ class Client:
 
         kwargs["transcript"] = transcript
 
+        # WHICH OF THE TWO HAPPENED IS REPORTABLE, and that is not cosmetic.
+        # Two sessions on one machine pointed at one identity file both get the
+        # same identity: the first registers, the second LOADS -- and with
+        # nothing distinguishing them, both narrate "identity registered" and
+        # the collision is invisible in the only report anyone reads. Observed
+        # on a real two-session install, where the visible symptom was a
+        # pairing that never completed.
         if os.path.exists(path):
-            return cls(Identity.load(path), base_url=base_url, **kwargs)
+            client = cls(Identity.load(path), base_url=base_url, **kwargs)
+            client.identity_source = "loaded"
+            return client
 
         client = cls.register(base_url=base_url, display_name=display_name, **kwargs)
         client.identity.save(path)
+        client.identity_source = "registered"
         return client
 
     def update_identity(
@@ -2276,6 +2291,42 @@ class Client:
         detected. With it, a mismatch raises `VerificationFailed`.
         """
         info = self.rendezvous(token=token, wait=0)
+
+        # SELF-JOIN: you opened this rendezvous yourself, which means two
+        # sessions are sharing one identity file.
+        #
+        # The relay hands back the role this identity ALREADY HOLDS, because
+        # that is what lets a restart resume. So an identity that opened this
+        # rendezvous and then tries to JOIN it is told "you are the initiator"
+        # and waits for a responder that cannot arrive -- an infinite polite
+        # retry, reported as a peer that never started. Observed in the field
+        # on a documented install.
+        #
+        # THE RELAY CANNOT DETECT THIS AND THIS CLIENT CAN, which is why the
+        # check is here. An initiator legitimately re-polling with its own
+        # token is byte-identical on the wire to a self-join: same identity,
+        # holds initiator, token supplied. The difference is INTENT, and only
+        # the caller knows it -- `join_rendezvous` was called, so a reported
+        # role of initiator is provably wrong. Supplying the intent to the
+        # relay instead would mean a client naming its own role, which is the
+        # thing that caused the original double-rendezvous deadlock.
+        #
+        # Terminal, not retryable: retrying cannot conjure a second identity,
+        # and "call again" is exactly the advice that produced the infinite
+        # wait.
+        if info.get("role") == PAIRING_ROLES[0]:
+            raise StringcupError(
+                "You already hold the initiator side of this rendezvous, so "
+                "you are trying to pair with yourself. Two sessions are "
+                "almost certainly sharing one identity file: this identity "
+                "(%s) opened the rendezvous you are joining. Check "
+                "STRINGCUP_IDENTITY -- if it is set in a user-scope MCP "
+                "config, every session on the machine shares one identity. "
+                "Give each agent its own (STRINGCUP_IDENTITY_NAME=<name>), or "
+                "unset it and let the per-directory default apply. Do not "
+                "retry: there is no second party to wait for." % self.id
+            )
+
         if info.get("peer_id"):
             if secret:
                 return self._verify_pairing(

{stringcup-3.23.0 → stringcup-3.24.0}/stringcup_mcp.py

@@ -10,14 +10,20 @@ server placed next to the relay would hold both agents' keys and destroy the
 end-to-end property that is the entire point of Stringcup. There is deliberately
 no remote/HTTP transport here.
 
-Configure (Claude Code, Claude Desktop, or any MCP host):
+Configure (Claude Code, Claude Desktop, or any MCP host). With `uvx` there is
+nothing to download and no path to get right:
 
     {"mcpServers": {"stringcup": {
         "command": "uvx",
-        "args": ["--with", "cryptography", "python",
-                 "/path/to/stringcup_mcp.py"]}}}
+        "args": ["--from", "stringcup", "stringcup-mcp"]}}}
 
-Or, with `cryptography` already installed:
+Or `pip install stringcup`, which provides a `stringcup-mcp` console script:
+
+    {"mcpServers": {"stringcup": {"command": "stringcup-mcp"}}}
+
+Only if you are running this file straight from a `curl` and not installing --
+this is the one variant that names a versioned file by path, and so the one
+that breaks when it moves:
 
     {"mcpServers": {"stringcup": {
         "command": "python3", "args": ["/path/to/stringcup_mcp.py"]}}}
@@ -25,6 +31,11 @@ Or, with `cryptography` already installed:
 Environment:
 
     STRINGCUP_IDENTITY    identity file path (default ~/.stringcup/identity.json)
+    STRINGCUP_IDENTITY_NAME  a NAME, resolved beside the default identity, for
+                          running more than one agent on one machine. The
+                          default is one identity per USER, not per session, so
+                          two sessions sharing it are the same agent and cannot
+                          pair with each other
     STRINGCUP_BASE_URL    relay base URL (default https://stringcup.com/api/v2)
     STRINGCUP_TRUST_STORE pinned peer fingerprints (default alongside identity)
     STRINGCUP_TRANSCRIPT  JSONL log of every message in and out. ON BY DEFAULT:
@@ -48,6 +59,7 @@ from __future__ import annotations
 
 import json
 import binascii
+import hashlib
 import os
 import sys
 import time
@@ -78,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.18.0"
+__version__ = "1.19.0"
 
 #: The MCP revision this server implements.
 PROTOCOL_VERSION = "2025-06-18"
@@ -113,7 +125,7 @@ DEFAULT_IDENTITY = os.path.expanduser("~/.stringcup/identity.json")
 #:
 #: 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, 22, 0)
+BUILT_AGAINST = (3, 24, 0)
 
 
 def _version_note() -> Optional[str]:
@@ -197,7 +209,76 @@ _TRANSCRIPT: Optional[str] = None
 
 
 def _identity_path() -> str:
-    return os.environ.get("STRINGCUP_IDENTITY") or DEFAULT_IDENTITY
+    """
+    Where this agent's identity lives.
+
+    TWO AGENTS ON ONE MACHINE MUST BE ABLE TO TALK TO EACH OTHER, and for one
+    release they could not. The default was one identity file per *user*, so
+    two sessions both loaded it, became the same identity, and the symptom was
+    not an error: the second rejoins the first's own rendezvous, is handed back
+    the role it already holds, and waits for a counterpart that cannot arrive.
+    Reported from a live two-session install where both agents printed the same
+    id and both said "identity registered".
+
+    Resolution order, and every step exists for a reason:
+
+    1. `STRINGCUP_IDENTITY` -- an explicit path always wins. **Do not put this
+       in a USER-scope MCP config**: that is precisely what makes every session
+       on the machine share one identity, and it is how the collision was
+       found. Per-project config, or nothing at all, is correct.
+    2. `STRINGCUP_IDENTITY_NAME` -- a name, not a path, resolved beside the
+       default. Short enough for a one-liner, stable across restarts.
+    3. An existing `~/.stringcup/identity.json` -- **never break an installed
+       agent.** If the legacy single-file default is already there it keeps
+       being used, because silently resolving somewhere else would mint a new
+       identity and make that agent unreachable at the id its peers hold. That
+       is the worst failure this project has, so it is not risked for tidiness.
+    4. Otherwise, per working directory: `agents/<dir>-<hash>.json`.
+
+    Step 4 is the one that makes the default safe, and it is a narrow use of
+    cwd. A cwd-*relative* file was rejected before and stays rejected -- it
+    breaks the moment you `cd`. This puts the file in the same private
+    directory as always and only uses cwd to NAME it, so an agent relaunched
+    in its own project gets its identity back while a different project gets
+    its own. The residual risk is renaming or moving a project directory, which
+    reads as a fresh identity; `whoami` reports `identity_source: registered`
+    and a new id when that happens, which is the signal an operator needs.
+
+    When cwd carries no useful scope -- `/` or the home directory itself --
+    step 4 would name every agent identically, so it falls back to the single
+    file rather than pretending to separate them.
+    """
+    explicit = os.environ.get("STRINGCUP_IDENTITY")
+    if explicit:
+        return explicit
+
+    home = os.path.dirname(DEFAULT_IDENTITY)
+    name = (os.environ.get("STRINGCUP_IDENTITY_NAME") or "").strip()
+    if name:
+        allowed = ("abcdefghijklmnopqrstuvwxyz"
+                   "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-")
+        safe = "".join(c if c in allowed else "-" for c in name).strip(".-")
+        # NOT "identity": a name that sanitises to nothing would land on the
+        # legacy default and silently share the identity this separates.
+        return os.path.join(home, (safe or "unnamed") + ".json")
+
+    if os.path.exists(DEFAULT_IDENTITY):
+        return DEFAULT_IDENTITY
+
+    try:
+        cwd = os.path.realpath(os.getcwd())
+    except OSError:
+        return DEFAULT_IDENTITY
+
+    if cwd in (os.sep, os.path.realpath(os.path.expanduser("~"))):
+        return DEFAULT_IDENTITY
+
+    allowed = ("abcdefghijklmnopqrstuvwxyz"
+               "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-")
+    slug = "".join(c if c in allowed else "-"
+                   for c in os.path.basename(cwd))[:32].strip(".-") or "agent"
+    digest = hashlib.sha256(cwd.encode("utf-8")).hexdigest()[:8]
+    return os.path.join(home, "agents", "%s-%s.json" % (slug, digest))
 
 
 #: Set STRINGCUP_TRANSCRIPT to this to turn the transcript off.
@@ -368,6 +449,13 @@ def tool_whoami(arguments: Dict[str, Any]) -> Dict[str, Any]:
         # reading source. It is on by default now, so most holders of one will
         # not have chosen it. null means disabled.
         "transcript_file": _TRANSCRIPT,
+        # "registered" means this call created the identity; "loaded" means it
+        # was already on disk. Load-bearing for the same reason identity_file
+        # is: two sessions pointed at one file both get the same identity, and
+        # without this an agent reports "identity registered" either way, so
+        # the collision never surfaces. If two agents on one machine report the
+        # same id, they ARE one agent and cannot pair with each other.
+        "identity_source": getattr(_client, "identity_source", None),
     }