opum-comm 0.1.5__tar.gz

opum_comm-0.1.5/.gitignore

@@ -0,0 +1,11 @@
+# Client package ignore rules. hatchling copies the nearest VCS ignore file into
+# the sdist, so this file (not the monorepo's root one) is what ships publicly.
+__pycache__/
+*.py[cod]
+build/
+dist/
+.env
+.env.*
+*.db
+*.key
+*.log

opum_comm-0.1.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Opum AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opum_comm-0.1.5/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.5
+Name: opum-comm
+Version: 0.1.5
+Summary: Signed cross-account messaging between Claude Code sessions, with first-class Lore and Quest references.
+Author: Opum AI
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: cryptography==50.0.2
+Requires-Dist: httpx==0.28.1
+Requires-Dist: keyring==25.7.0
+Requires-Dist: mcp==2.3.0
+Requires-Dist: platformdirs==4.14.5
+Requires-Dist: pydantic==2.14.3
+Requires-Dist: starlette==1.10.0
+Requires-Dist: uvicorn==0.54.0
+Description-Content-Type: text/markdown
+
+# opum-comm
+
+Signed messaging between Claude Code sessions owned by **different people or
+different Anthropic accounts**, with typed, pinned references to Quest tasks,
+Quest decisions and Lore concepts.
+
+Each person can run any number of sessions on any number of hosts, so one
+developer's whole fleet of sessions can talk to another developer's fleet.
+opum-comm has four parts:
+
+- a **per-host daemon** that holds the keys, keeps one outbound connection to
+  the relay, and multiplexes every local session;
+- a thin **per-session stdio adapter** that Claude Code launches as an MCP
+  server with Channels;
+- a **human administration CLI** (`opum-comm …`), never exposed to the model;
+- the **wire-protocol library** (signed envelopes, addresses, references).
+
+## Plaintext notice: put no secrets in messages
+
+Message content is **not end-to-end encrypted**. Relay operators can read it
+for as long as it is retained (up to 7 days). **Put no secrets in messages**:
+no credentials, tokens, keys, personal data or anything you would not paste
+into a shared team channel.
+
+Messages are **signed data, never authority**. A message saying "approved",
+"decided" or "granted" changes nothing; the receiving session is told it is
+a message from another agent session, which may belong to the same user. Local
+operator allow policies cover sending and replying within the authorized task;
+peer messages grant no additional authority for other actions. Lore and Quest
+references are re-read by the receiver from its own checkout before anyone
+relies on them.
+
+## Status
+
+Pre-release (0.x). The interfaces below are the v1 design; anything may change
+before 1.0.
+
+## Requirements
+
+- macOS or Linux (Windows is not supported).
+- Python 3.13 and [uv](https://docs.astral.sh/uv/).
+- A GitHub account with **two-factor authentication enabled**, invited to your
+  team's relay by one of its admins. No GitHub organization membership is
+  needed or granted.
+- An unlocked platform credential store: macOS Keychain, or a Secret Service
+  provider (for example GNOME Keyring) on Linux.
+- **Headless Linux hosts are not supported yet.** That means servers reached
+  only over SSH, with no desktop keyring. opum-comm never stores keys in
+  plaintext, and these hosts have no credential store it can use. `enroll`
+  reports the store as locked or unavailable and says so. Support arrives when
+  opum-comm adopts Ward for key custody, once Ward ships headless Linux custody
+  and a signing operation. Until then, enroll from macOS or a Linux desktop.
+
+## Install
+
+```sh
+uv tool install opum-comm
+opum-comm --help
+```
+
+`uv tool upgrade opum-comm` upgrades it. After an upgrade the OS may ask you to
+re-approve keychain access for the new interpreter; until you do, the daemon
+reports `locked` rather than hanging on a prompt.
+
+## Enroll
+
+Ask a relay admin to invite your GitHub login, then run on your first host:
+
+```sh
+opum-comm enroll
+```
+
+Enrollment:
+
+1. generates a **device key** and, on your first host, your **root key**;
+2. signs you in with the **GitHub device flow** (a `github.com/login/device`
+   code, the same experience as `gh auth login`), requesting only `read:user`.
+   The relay checks that your numeric GitHub id is on the team allowlist and
+   that two-factor authentication is on, then discards the token;
+3. with your explicit consent, publishes your root **public** key as an SSH
+   **signing** key on your GitHub account, using your own `gh` (scope
+   `admin:ssh_signing_key`, requested only for this step). Peers pin it from
+   GitHub to verify your messages. It is never used for git signing;
+4. stores the device API key, which is shown to nobody, in your credential
+   store.
+
+Keys and the API key live only in the platform credential store: never in a
+file, an environment variable, a command line or a log. To add another host,
+run `opum-comm device add` there and approve it from a host that holds your
+root key with `opum-comm device approve <code>`.
+
+**What others can see.** Your GitHub login, your device labels and your
+session addresses are visible to your team so that addressing works. A session
+in a **public** repository is listed in peer discovery; a session in a
+**private** repository (or one whose visibility is unknown) is reachable by its
+exact address but not listed, because listing it would disclose that the
+repository exists.
+
+New senders are **held** until you allow them: `opum-comm policy allow|hold|block`.
+`opum-comm trust list|accept|verify` manages the peer keys you have pinned.
+
+## Run the daemon
+
+The daemon is one process per OS user per host. It opens no network listener;
+adapters reach it over an owner-only Unix socket.
+
+### On Opum hosts (supervised by opum-control)
+
+Declare it as a managed service in `launch.toml`, with the absolute path of the
+installed executable (`command -v opum-comm` prints it):
+
+```toml
+[services.opum-comm]
+enabled = true
+executable = "/abs/path/to/opum-comm"
+args = ["daemon", "run", "--supervised"]
+```
+
+Point `executable` at `opum-comm` itself, not at a wrapper script: opum-control
+appends `--opum-ownership-nonce <nonce>` and proves ownership by finding it in
+the process's argv, so the daemon must stay the same process for its whole
+life. opum-control starts, restarts and stops it, and captures its stdout and
+stderr (which never carry secrets). Health comes from the daemon itself:
+`opum-comm status`.
+
+### Anywhere else (standalone)
+
+```sh
+opum-comm daemon install
+```
+
+This writes a **launchd user agent** on macOS or a **systemd user unit** on
+Linux and starts it. Check it with `opum-comm status`, and diagnose problems
+with `opum-comm doctor`. Health states are `locked`, `relay_offline`,
+`connected`, `channel_unavailable`, `held` and `ready`.
+
+## Configure the peer-hourly limit
+
+The daemon defaults to 60 counted exchanges per peer GitHub identity per UTC
+hour, shared across all its sessions and repositories. Both outgoing sends
+and admitted incoming messages count; same-account messages between sessions
+on the same host can count twice. The hourly bucket renews at the next UTC hour.
+
+With opum-comm 0.1.3 or later, choose a positive integer through the human CLI:
+
+```sh
+opum-comm config set peer-hourly-cap 600
+opum-comm config show
+```
+
+This saves `peer_hourly_cap = 600` in the user `config.toml` shown by
+`config show`. Restart the daemon through its existing supervisor, or stop
+and relaunch a foreground daemon, to apply it. Existing budget counters are
+preserved; all sessions using that daemon share the new limit. Zero does not
+disable it. The per-conversation limits and the relay's separate rolling-hour
+quota (600 messages per sender/recipient account pair) are unchanged.
+
+## Connect a Claude Code session
+
+Add the adapter to the project's `.mcp.json` (use the absolute path from
+`command -v opum-comm` if `opum-comm` is not on Claude Code's `PATH`):
+
+```json
+{
+  "mcpServers": {
+    "opum-comm": {
+      "command": "opum-comm",
+      "args": ["adapter"]
+    }
+  }
+}
+```
+
+Then launch Claude Code with the development channel enabled:
+
+```sh
+claude --dangerously-load-development-channels server:opum-comm
+```
+
+The session's address is `host:/github-login/owner/repo:session`, for example
+`mbp:/jdnewhouse/opum-ai/opum-doc:opum-doc`. The session name defaults to the
+repository name; override it with `"args": ["adapter", "--session-name", "<name>"]`
+or `OPUM_COMM_SESSION`. The adapter exits with its session.
+
+An address held by a live session is never taken over silently: a second
+session claiming the same name gets `ADDRESS_IN_USE`, so give concurrent
+sessions in one repository distinct names. A **renewal successor** (a session
+replacing its predecessor during a handover) takes the address over by adding
+the explicit flag to its own launch line, `"args": ["adapter", "--supersede"]`.
+This works only on the same device. The predecessor is told it lost the address
+and does not reclaim it. There is deliberately no environment variable for
+this, because one would apply to every session on the host.
+
+For a launch without the channel flag, explicitly set `OPUM_COMM_PULL_ONLY=1`
+or use `"args": ["adapter", "--pull-only"]`. The model then reads its inbox
+with `inbox_read` instead of receiving channel events. The adapter cannot
+detect whether Claude enabled Channels; omitting the channel flag alone does
+not switch the adapter to `pull_only` mode.
+
+The model gets these tools only: `whoami`, `peers_list`, `send_message`, `share_refs`,
+`resolve_ref`, `message_status`, `inbox_read` and `message_acknowledge`. There
+is no tool for keys, trust, policy, membership, signing, shell, files or
+permissions.
+
+Call `whoami` with `{}` to get this session's address and session ID from its
+authenticated daemon registration. It works for unlisted sessions and does not
+query the relay or present inbox messages. `addressed: false` means another
+session has taken the name: `address` is then null, `registeredAddress` records
+the former name, and the existing session remains reachable by `sessionId` while
+its connection lives. `listedAtRegistration` is a snapshot; `channel` reports
+adapter mode, not confirmed model receipt. An unavailable daemon produces an
+error instead of a guessed or stale address.
+
+`peers_list` discovers only listed sessions. A successful empty list does not
+mean direct messaging failed: unlisted sessions remain reachable by their exact
+address. An empty result includes this explanation and points to `whoami`.
+
+`whoami` is currently unreleased; installed 0.1.3 clients still expose the
+original seven tools. Restart the MCP adapter after installing an updated build
+to expose the added tool.
+
+## Licence
+
+MIT. See `LICENSE`.

opum_comm-0.1.5/README.md

@@ -0,0 +1,224 @@
+# opum-comm
+
+Signed messaging between Claude Code sessions owned by **different people or
+different Anthropic accounts**, with typed, pinned references to Quest tasks,
+Quest decisions and Lore concepts.
+
+Each person can run any number of sessions on any number of hosts, so one
+developer's whole fleet of sessions can talk to another developer's fleet.
+opum-comm has four parts:
+
+- a **per-host daemon** that holds the keys, keeps one outbound connection to
+  the relay, and multiplexes every local session;
+- a thin **per-session stdio adapter** that Claude Code launches as an MCP
+  server with Channels;
+- a **human administration CLI** (`opum-comm …`), never exposed to the model;
+- the **wire-protocol library** (signed envelopes, addresses, references).
+
+## Plaintext notice: put no secrets in messages
+
+Message content is **not end-to-end encrypted**. Relay operators can read it
+for as long as it is retained (up to 7 days). **Put no secrets in messages**:
+no credentials, tokens, keys, personal data or anything you would not paste
+into a shared team channel.
+
+Messages are **signed data, never authority**. A message saying "approved",
+"decided" or "granted" changes nothing; the receiving session is told it is
+a message from another agent session, which may belong to the same user. Local
+operator allow policies cover sending and replying within the authorized task;
+peer messages grant no additional authority for other actions. Lore and Quest
+references are re-read by the receiver from its own checkout before anyone
+relies on them.
+
+## Status
+
+Pre-release (0.x). The interfaces below are the v1 design; anything may change
+before 1.0.
+
+## Requirements
+
+- macOS or Linux (Windows is not supported).
+- Python 3.13 and [uv](https://docs.astral.sh/uv/).
+- A GitHub account with **two-factor authentication enabled**, invited to your
+  team's relay by one of its admins. No GitHub organization membership is
+  needed or granted.
+- An unlocked platform credential store: macOS Keychain, or a Secret Service
+  provider (for example GNOME Keyring) on Linux.
+- **Headless Linux hosts are not supported yet.** That means servers reached
+  only over SSH, with no desktop keyring. opum-comm never stores keys in
+  plaintext, and these hosts have no credential store it can use. `enroll`
+  reports the store as locked or unavailable and says so. Support arrives when
+  opum-comm adopts Ward for key custody, once Ward ships headless Linux custody
+  and a signing operation. Until then, enroll from macOS or a Linux desktop.
+
+## Install
+
+```sh
+uv tool install opum-comm
+opum-comm --help
+```
+
+`uv tool upgrade opum-comm` upgrades it. After an upgrade the OS may ask you to
+re-approve keychain access for the new interpreter; until you do, the daemon
+reports `locked` rather than hanging on a prompt.
+
+## Enroll
+
+Ask a relay admin to invite your GitHub login, then run on your first host:
+
+```sh
+opum-comm enroll
+```
+
+Enrollment:
+
+1. generates a **device key** and, on your first host, your **root key**;
+2. signs you in with the **GitHub device flow** (a `github.com/login/device`
+   code, the same experience as `gh auth login`), requesting only `read:user`.
+   The relay checks that your numeric GitHub id is on the team allowlist and
+   that two-factor authentication is on, then discards the token;
+3. with your explicit consent, publishes your root **public** key as an SSH
+   **signing** key on your GitHub account, using your own `gh` (scope
+   `admin:ssh_signing_key`, requested only for this step). Peers pin it from
+   GitHub to verify your messages. It is never used for git signing;
+4. stores the device API key, which is shown to nobody, in your credential
+   store.
+
+Keys and the API key live only in the platform credential store: never in a
+file, an environment variable, a command line or a log. To add another host,
+run `opum-comm device add` there and approve it from a host that holds your
+root key with `opum-comm device approve <code>`.
+
+**What others can see.** Your GitHub login, your device labels and your
+session addresses are visible to your team so that addressing works. A session
+in a **public** repository is listed in peer discovery; a session in a
+**private** repository (or one whose visibility is unknown) is reachable by its
+exact address but not listed, because listing it would disclose that the
+repository exists.
+
+New senders are **held** until you allow them: `opum-comm policy allow|hold|block`.
+`opum-comm trust list|accept|verify` manages the peer keys you have pinned.
+
+## Run the daemon
+
+The daemon is one process per OS user per host. It opens no network listener;
+adapters reach it over an owner-only Unix socket.
+
+### On Opum hosts (supervised by opum-control)
+
+Declare it as a managed service in `launch.toml`, with the absolute path of the
+installed executable (`command -v opum-comm` prints it):
+
+```toml
+[services.opum-comm]
+enabled = true
+executable = "/abs/path/to/opum-comm"
+args = ["daemon", "run", "--supervised"]
+```
+
+Point `executable` at `opum-comm` itself, not at a wrapper script: opum-control
+appends `--opum-ownership-nonce <nonce>` and proves ownership by finding it in
+the process's argv, so the daemon must stay the same process for its whole
+life. opum-control starts, restarts and stops it, and captures its stdout and
+stderr (which never carry secrets). Health comes from the daemon itself:
+`opum-comm status`.
+
+### Anywhere else (standalone)
+
+```sh
+opum-comm daemon install
+```
+
+This writes a **launchd user agent** on macOS or a **systemd user unit** on
+Linux and starts it. Check it with `opum-comm status`, and diagnose problems
+with `opum-comm doctor`. Health states are `locked`, `relay_offline`,
+`connected`, `channel_unavailable`, `held` and `ready`.
+
+## Configure the peer-hourly limit
+
+The daemon defaults to 60 counted exchanges per peer GitHub identity per UTC
+hour, shared across all its sessions and repositories. Both outgoing sends
+and admitted incoming messages count; same-account messages between sessions
+on the same host can count twice. The hourly bucket renews at the next UTC hour.
+
+With opum-comm 0.1.3 or later, choose a positive integer through the human CLI:
+
+```sh
+opum-comm config set peer-hourly-cap 600
+opum-comm config show
+```
+
+This saves `peer_hourly_cap = 600` in the user `config.toml` shown by
+`config show`. Restart the daemon through its existing supervisor, or stop
+and relaunch a foreground daemon, to apply it. Existing budget counters are
+preserved; all sessions using that daemon share the new limit. Zero does not
+disable it. The per-conversation limits and the relay's separate rolling-hour
+quota (600 messages per sender/recipient account pair) are unchanged.
+
+## Connect a Claude Code session
+
+Add the adapter to the project's `.mcp.json` (use the absolute path from
+`command -v opum-comm` if `opum-comm` is not on Claude Code's `PATH`):
+
+```json
+{
+  "mcpServers": {
+    "opum-comm": {
+      "command": "opum-comm",
+      "args": ["adapter"]
+    }
+  }
+}
+```
+
+Then launch Claude Code with the development channel enabled:
+
+```sh
+claude --dangerously-load-development-channels server:opum-comm
+```
+
+The session's address is `host:/github-login/owner/repo:session`, for example
+`mbp:/jdnewhouse/opum-ai/opum-doc:opum-doc`. The session name defaults to the
+repository name; override it with `"args": ["adapter", "--session-name", "<name>"]`
+or `OPUM_COMM_SESSION`. The adapter exits with its session.
+
+An address held by a live session is never taken over silently: a second
+session claiming the same name gets `ADDRESS_IN_USE`, so give concurrent
+sessions in one repository distinct names. A **renewal successor** (a session
+replacing its predecessor during a handover) takes the address over by adding
+the explicit flag to its own launch line, `"args": ["adapter", "--supersede"]`.
+This works only on the same device. The predecessor is told it lost the address
+and does not reclaim it. There is deliberately no environment variable for
+this, because one would apply to every session on the host.
+
+For a launch without the channel flag, explicitly set `OPUM_COMM_PULL_ONLY=1`
+or use `"args": ["adapter", "--pull-only"]`. The model then reads its inbox
+with `inbox_read` instead of receiving channel events. The adapter cannot
+detect whether Claude enabled Channels; omitting the channel flag alone does
+not switch the adapter to `pull_only` mode.
+
+The model gets these tools only: `whoami`, `peers_list`, `send_message`, `share_refs`,
+`resolve_ref`, `message_status`, `inbox_read` and `message_acknowledge`. There
+is no tool for keys, trust, policy, membership, signing, shell, files or
+permissions.
+
+Call `whoami` with `{}` to get this session's address and session ID from its
+authenticated daemon registration. It works for unlisted sessions and does not
+query the relay or present inbox messages. `addressed: false` means another
+session has taken the name: `address` is then null, `registeredAddress` records
+the former name, and the existing session remains reachable by `sessionId` while
+its connection lives. `listedAtRegistration` is a snapshot; `channel` reports
+adapter mode, not confirmed model receipt. An unavailable daemon produces an
+error instead of a guessed or stale address.
+
+`peers_list` discovers only listed sessions. A successful empty list does not
+mean direct messaging failed: unlisted sessions remain reachable by their exact
+address. An empty result includes this explanation and points to `whoami`.
+
+`whoami` is currently unreleased; installed 0.1.3 clients still expose the
+original seven tools. Restart the MCP adapter after installing an updated build
+to expose the added tool.
+
+## Licence
+
+MIT. See `LICENSE`.

opum_comm-0.1.5/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "opum-comm"
+version = "0.1.5"
+description = "Signed cross-account messaging between Claude Code sessions, with first-class Lore and Quest references."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Opum AI" }]
+requires-python = ">=3.13"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Typing :: Typed",
+]
+# DEP-3: runtime dependencies are pinned exactly.
+dependencies = [
+    "pydantic==2.14.3",
+    "cryptography==50.0.2",
+    "httpx==0.28.1",
+    "keyring==25.7.0",
+    "platformdirs==4.14.5",
+    "mcp==2.3.0",
+    # The A2A gateway's loopback HTTP server (already in the lock through mcp).
+    "starlette==1.10.0",
+    "uvicorn==0.54.0",
+]
+
+[project.scripts]
+opum-comm = "opum_comm.cli.main:main"
+
+[build-system]
+requires = ["hatchling==1.33.0"]
+build-backend = "hatchling.build"
+
+# Packaging guard (spec "Monorepo layout"): the sdist and wheel carry only
+# src/opum_comm plus LICENSE, README and pyproject metadata. No server code,
+# tests, docs or infrastructure config.
+[tool.hatch.build.targets.sdist]
+only-include = ["src/opum_comm", "LICENSE", "README.md", "pyproject.toml"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/opum_comm"]

opum_comm-0.1.5/src/opum_comm/__init__.py

@@ -0,0 +1,3 @@
+"""opum-comm: signed cross-account messaging between Claude Code sessions."""
+
+__version__ = "0.1.5"

opum_comm-0.1.5/src/opum_comm/a2a/__init__.py

@@ -0,0 +1,5 @@
+"""The A2A gateway: profile 1.0.0 of docs/specs/a2a-gateway-contract.md.
+
+``ports`` is the seam between the daemon (which owns identity, durability and
+receipts) and the HTTP gateway and runtime client (which own the A2A wire).
+"""