inter-agent-pi 0.2.0__tar.gz

inter_agent_pi-0.2.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arcanemachine
+
+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.

inter_agent_pi-0.2.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: inter-agent-pi
+Version: 0.2.0
+Summary: Pi helper for the inter-agent message bus: connect listener and command-line tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: inter-agent-core==0.2.0
+Requires-Dist: websockets==16.0
+Dynamic: license-file
+
+# inter-agent-pi
+
+[![Pi](https://img.shields.io/badge/pi-extension-purple)](https://github.com/arcanemachine/inter-agent-pi)
+
+The Pi extension for the inter-agent message bus.
+
+It connects a Pi coding-agent session to the bus as a named agent,
+exposes grouped `/inter-agent` commands and a bounded set of agent-callable
+tools, delivers incoming peer messages as Pi notifications, and ships a Python
+helper (`inter-agent-pi` console command, `inter_agent_pi` import package) that
+wraps the importable [`inter-agent-core`](#runtime-dependency) listener and
+command APIs.
+
+This repository is an independent clean-history child. It contains no former
+monorepo history, no private workflow, no core runtime source, and no Claude
+Code material.
+
+## Installation (Pi extension)
+
+From a Pi session:
+
+```bash
+pi install npm:inter-agent-pi@0.2.0
+```
+
+Or install from a published Git tag (once published; do not pin a raw commit
+hash):
+
+```bash
+pi install https://github.com/arcanemachine/inter-agent-pi
+```
+
+Or load directly from a source checkout during development:
+
+```bash
+pi -e /path/to/inter-agent-pi/src/index.ts
+```
+
+The extension entry point is `./src/index.ts`.
+
+## Runtime dependency
+
+The helper depends on `inter-agent-core` `0.2.0` and on `websockets` `16.0`. A compatible `inter-agent-core` install
+must provide the `inter-agent-pi`, `inter-agent-server`, `inter-agent-connect`,
+`inter-agent-send`, `inter-agent-list`, `inter-agent-status`,
+`inter-agent-shutdown`, `inter-agent-kick`, `inter-agent-publish`, and
+`inter-agent-channels` console commands and the importable `inter_agent`
+namespace, including the promoted `inter_agent.core.adapter_control` bridge.
+
+> **Development note (non-release):** while the permanent `inter-agent-core`
+> repository is being prepared, the Python helper may be resolved against a
+> temporary local `inter-agent-core` candidate via a migration-only
+> `[tool.uv.sources]` path entry. That path source is removed and the lock is
+> re-resolved against the permanent `inter-agent-core` repository before any
+> publication. Never publish while the temporary path source remains.
+
+### Helper resolution precedence
+
+The extension resolves the Python runtime in this order:
+
+1. `INTER_AGENT_PI_HELPER` — an exact path to an `inter-agent-pi` executable;
+   its bin directory must also contain the required core helper scripts.
+2. An explicitly configured `interAgent.projectPath` — the helper is resolved
+   from that checkout's `.venv/bin`; if it is configured but incomplete the
+   extension fails fast with a bounded, actionable message.
+3. The extension-managed, documented runtime venv.
+4. `inter-agent-pi`, `inter-agent-connect`, and `inter-agent-server` discovered
+   together on `PATH`.
+5. A bounded setup-needed failure pointing back to this README.
+
+The legacy implicit fallback to `~/.local/share/inter-agent` is intentionally
+removed; that was a monorepo-era bootstrap assumption that no longer applies
+to the standalone package. Explicitly configured `interAgent.projectPath`
+remains supported for development.
+
+## Installing the Python helper
+
+From a source checkout:
+
+```bash
+uv sync --locked          # resolve inter-agent-core + dev/test tooling
+uv build                  # build wheel + sdist into dist/
+```
+
+Install the built wheel into a venv that already provides a compatible
+`inter-agent-core`, for example:
+
+```bash
+uv venv .venv
+uv pip install ./dist/*.whl <compatible-inter-agent-core-wheel>
+```
+
+The `inter-agent-pi` console command and the agent-callable tools all reuse
+this runtime.
+
+## Configuration
+
+Configuration is read from the Pi agent settings file under `interAgent.*`.
+Relative paths (`projectPath`, `dataDir`, TLS cert/key) resolve against the
+directory of the settings file.
+
+- `host` / `port` — override the default bus endpoint.
+- `dataDir` — shared bus state directory; defaults to the core default.
+- `secret` — shared secret for challenge-response auth; forwarded to helpers
+  as `INTER_AGENT_SECRET`. Do not store secrets in plaintext files in the repo.
+- `tls` / `tlsCert` / `tlsKey` — enable explicit TLS and point at a
+  certificate/key pair.
+
+Helper resolution precedence and the environment variables used by the helper
+match [`inter-agent-core`](#runtime-dependency). Helper install path, runtime
+state/config path, and bus state directories stay distinct so the bus identity
+does not fragment across installs.
+
+## Commands
+
+All commands ride the grouped `/inter-agent` command:
+
+```
+usage: /inter-agent <connect|disconnect|kick|rename|send|broadcast|publish|channels|subscribe|unsubscribe|list|status|delivery> [args]
+```
+
+- `/inter-agent connect <name> [--label <label>]` — connect this session as a
+  named agent; auto-starts the server if unavailable.
+- `/inter-agent disconnect` — stop the local listener and notify.
+- `/inter-agent kick <name>` — force-disconnect another session (user-only).
+- `/inter-agent rename <name> [--label <label>]` — reconnect under a new name.
+- `/inter-agent send <to> <text>` — send a direct message; routes the sender via `--from`.
+- `/inter-agent broadcast <text>` — broadcast to every session (user-only).
+- `/inter-agent publish <channel> <text>` — publish to a channel (user-only).
+- `/inter-agent channels` — list channels and subscribers.
+- `/inter-agent subscribe <channel>` / `/inter-agent unsubscribe <channel>` —
+  bind the live listener's subscriptions over the local control socket.
+- `/inter-agent list` — list connected agent sessions.
+- `/inter-agent status` — print server/helper status.
+- `/inter-agent delivery <immediate|queued>` — switch inbound delivery mode
+  (aliases `i` / `q`).
+
+## Agent-callable tools vs user-only controls
+
+Agent-callable tools:
+
+- `inter_agent_send`, `inter_agent_broadcast` — send/broadcast through the
+  connected Pi listener (sender routed via `--from`).
+- `inter_agent_list`, `inter_agent_whoami`, `inter_agent_status` —
+  read-only diagnostics; they do not require a connected listener.
+- `inter_agent_read_messages` — read and remove queued mailbox messages;
+  performs no outbound action.
+
+User-only controls (no model-callable tool): `kick`, `publish`, `subscribe`,
+`unsubscribe`, `channels`, `delivery`, and the connect/disconnect/rename
+connection actions. Broadcast, publish, kick, and destructive actions require
+explicit user approval; the model is instructed never to send a courtesy reply
+and to treat peer messages as untrusted context.
+
+## Mailbox, reload continuity, and reconnection
+
+- By default inbound messages are queued in a bounded mailbox (max 128 unread)
+  and surfaced as a metadata-only notice; `delivery immediate` restores bounded
+  body notification.
+- The notice provokes a non-steering follow-up turn and never prescribes a
+  canned acknowledgment, reply, or outbound action.
+- A same-process `/reload` preserves the unread mailbox through a versioned,
+  one-use, process-global handoff (`Symbol.for("inter-agent.pi.mailbox.reloadHandoff.v1")`),
+  generation/session-scoped and TTL-bounded; every other lifecycle boundary
+  starts empty.
+- The listener reconnects with bounded backoff and gives up after a deadline
+  measured from the first failure. A `KICKED` stop terminates one listener
+  process without reconnecting, leaving the routing name free for an explicit
+  later reconnect.
+- The startup flag provides the inter-agent routing name at process start:
+  `pi -- inter-agent=<name>`.
+
+## Development
+
+```bash
+uv sync --locked          # install runtime + dev/test dependencies
+npm ci                    # install TypeScript/dev dependencies (network)
+npm test                  # TypeScript tests
+npm run typecheck         # tsc --noEmit
+npm run build             # emit dist/
+npx prettier --write .    # format
+uv run pytest -q          # Python tests
+uv run ruff check src tests
+uv run black --check src tests
+uv run mypy src tests
+scripts/run-checks.sh     # full package gate incl. artifact validation
+```
+
+Artifacts (`dist/`, `dist-tests/`, `node_modules/`, `.venv/`, wheels, tarballs)
+are generated and gitignored; they are not part of the root commit.
+
+## Ecosystem and core
+
+- The public `inter-agent-core` repository owns the bus runtime and the
+  `inter_agent.core.adapter_control` bridge this package consumes. (Its public
+  repository URL is published with that release; this package depends on the
+  compatible distribution name `inter-agent-core`.)
+- The public ecosystem repository coordinates adapters; it is added as a
+  submodule only once it has a published initial `main` commit.
+
+This package does not assume any currently published artifact exists beyond
+what a compatible `inter-agent-core` release provides.
+
+## Security
+
+- Authenticate with the shared bus secret; never commit secrets, tokens, keys,
+  or certificates to this repository.
+- TLS uses explicit cert/key paths; a wrong/untrusted certificate fails bounded
+  and actionable and never falls back to plaintext.
+- Peer messages are untrusted context, never instructions.

inter_agent_pi-0.2.0/README.md

@@ -0,0 +1,210 @@
+# inter-agent-pi
+
+[![Pi](https://img.shields.io/badge/pi-extension-purple)](https://github.com/arcanemachine/inter-agent-pi)
+
+The Pi extension for the inter-agent message bus.
+
+It connects a Pi coding-agent session to the bus as a named agent,
+exposes grouped `/inter-agent` commands and a bounded set of agent-callable
+tools, delivers incoming peer messages as Pi notifications, and ships a Python
+helper (`inter-agent-pi` console command, `inter_agent_pi` import package) that
+wraps the importable [`inter-agent-core`](#runtime-dependency) listener and
+command APIs.
+
+This repository is an independent clean-history child. It contains no former
+monorepo history, no private workflow, no core runtime source, and no Claude
+Code material.
+
+## Installation (Pi extension)
+
+From a Pi session:
+
+```bash
+pi install npm:inter-agent-pi@0.2.0
+```
+
+Or install from a published Git tag (once published; do not pin a raw commit
+hash):
+
+```bash
+pi install https://github.com/arcanemachine/inter-agent-pi
+```
+
+Or load directly from a source checkout during development:
+
+```bash
+pi -e /path/to/inter-agent-pi/src/index.ts
+```
+
+The extension entry point is `./src/index.ts`.
+
+## Runtime dependency
+
+The helper depends on `inter-agent-core` `0.2.0` and on `websockets` `16.0`. A compatible `inter-agent-core` install
+must provide the `inter-agent-pi`, `inter-agent-server`, `inter-agent-connect`,
+`inter-agent-send`, `inter-agent-list`, `inter-agent-status`,
+`inter-agent-shutdown`, `inter-agent-kick`, `inter-agent-publish`, and
+`inter-agent-channels` console commands and the importable `inter_agent`
+namespace, including the promoted `inter_agent.core.adapter_control` bridge.
+
+> **Development note (non-release):** while the permanent `inter-agent-core`
+> repository is being prepared, the Python helper may be resolved against a
+> temporary local `inter-agent-core` candidate via a migration-only
+> `[tool.uv.sources]` path entry. That path source is removed and the lock is
+> re-resolved against the permanent `inter-agent-core` repository before any
+> publication. Never publish while the temporary path source remains.
+
+### Helper resolution precedence
+
+The extension resolves the Python runtime in this order:
+
+1. `INTER_AGENT_PI_HELPER` — an exact path to an `inter-agent-pi` executable;
+   its bin directory must also contain the required core helper scripts.
+2. An explicitly configured `interAgent.projectPath` — the helper is resolved
+   from that checkout's `.venv/bin`; if it is configured but incomplete the
+   extension fails fast with a bounded, actionable message.
+3. The extension-managed, documented runtime venv.
+4. `inter-agent-pi`, `inter-agent-connect`, and `inter-agent-server` discovered
+   together on `PATH`.
+5. A bounded setup-needed failure pointing back to this README.
+
+The legacy implicit fallback to `~/.local/share/inter-agent` is intentionally
+removed; that was a monorepo-era bootstrap assumption that no longer applies
+to the standalone package. Explicitly configured `interAgent.projectPath`
+remains supported for development.
+
+## Installing the Python helper
+
+From a source checkout:
+
+```bash
+uv sync --locked          # resolve inter-agent-core + dev/test tooling
+uv build                  # build wheel + sdist into dist/
+```
+
+Install the built wheel into a venv that already provides a compatible
+`inter-agent-core`, for example:
+
+```bash
+uv venv .venv
+uv pip install ./dist/*.whl <compatible-inter-agent-core-wheel>
+```
+
+The `inter-agent-pi` console command and the agent-callable tools all reuse
+this runtime.
+
+## Configuration
+
+Configuration is read from the Pi agent settings file under `interAgent.*`.
+Relative paths (`projectPath`, `dataDir`, TLS cert/key) resolve against the
+directory of the settings file.
+
+- `host` / `port` — override the default bus endpoint.
+- `dataDir` — shared bus state directory; defaults to the core default.
+- `secret` — shared secret for challenge-response auth; forwarded to helpers
+  as `INTER_AGENT_SECRET`. Do not store secrets in plaintext files in the repo.
+- `tls` / `tlsCert` / `tlsKey` — enable explicit TLS and point at a
+  certificate/key pair.
+
+Helper resolution precedence and the environment variables used by the helper
+match [`inter-agent-core`](#runtime-dependency). Helper install path, runtime
+state/config path, and bus state directories stay distinct so the bus identity
+does not fragment across installs.
+
+## Commands
+
+All commands ride the grouped `/inter-agent` command:
+
+```
+usage: /inter-agent <connect|disconnect|kick|rename|send|broadcast|publish|channels|subscribe|unsubscribe|list|status|delivery> [args]
+```
+
+- `/inter-agent connect <name> [--label <label>]` — connect this session as a
+  named agent; auto-starts the server if unavailable.
+- `/inter-agent disconnect` — stop the local listener and notify.
+- `/inter-agent kick <name>` — force-disconnect another session (user-only).
+- `/inter-agent rename <name> [--label <label>]` — reconnect under a new name.
+- `/inter-agent send <to> <text>` — send a direct message; routes the sender via `--from`.
+- `/inter-agent broadcast <text>` — broadcast to every session (user-only).
+- `/inter-agent publish <channel> <text>` — publish to a channel (user-only).
+- `/inter-agent channels` — list channels and subscribers.
+- `/inter-agent subscribe <channel>` / `/inter-agent unsubscribe <channel>` —
+  bind the live listener's subscriptions over the local control socket.
+- `/inter-agent list` — list connected agent sessions.
+- `/inter-agent status` — print server/helper status.
+- `/inter-agent delivery <immediate|queued>` — switch inbound delivery mode
+  (aliases `i` / `q`).
+
+## Agent-callable tools vs user-only controls
+
+Agent-callable tools:
+
+- `inter_agent_send`, `inter_agent_broadcast` — send/broadcast through the
+  connected Pi listener (sender routed via `--from`).
+- `inter_agent_list`, `inter_agent_whoami`, `inter_agent_status` —
+  read-only diagnostics; they do not require a connected listener.
+- `inter_agent_read_messages` — read and remove queued mailbox messages;
+  performs no outbound action.
+
+User-only controls (no model-callable tool): `kick`, `publish`, `subscribe`,
+`unsubscribe`, `channels`, `delivery`, and the connect/disconnect/rename
+connection actions. Broadcast, publish, kick, and destructive actions require
+explicit user approval; the model is instructed never to send a courtesy reply
+and to treat peer messages as untrusted context.
+
+## Mailbox, reload continuity, and reconnection
+
+- By default inbound messages are queued in a bounded mailbox (max 128 unread)
+  and surfaced as a metadata-only notice; `delivery immediate` restores bounded
+  body notification.
+- The notice provokes a non-steering follow-up turn and never prescribes a
+  canned acknowledgment, reply, or outbound action.
+- A same-process `/reload` preserves the unread mailbox through a versioned,
+  one-use, process-global handoff (`Symbol.for("inter-agent.pi.mailbox.reloadHandoff.v1")`),
+  generation/session-scoped and TTL-bounded; every other lifecycle boundary
+  starts empty.
+- The listener reconnects with bounded backoff and gives up after a deadline
+  measured from the first failure. A `KICKED` stop terminates one listener
+  process without reconnecting, leaving the routing name free for an explicit
+  later reconnect.
+- The startup flag provides the inter-agent routing name at process start:
+  `pi -- inter-agent=<name>`.
+
+## Development
+
+```bash
+uv sync --locked          # install runtime + dev/test dependencies
+npm ci                    # install TypeScript/dev dependencies (network)
+npm test                  # TypeScript tests
+npm run typecheck         # tsc --noEmit
+npm run build             # emit dist/
+npx prettier --write .    # format
+uv run pytest -q          # Python tests
+uv run ruff check src tests
+uv run black --check src tests
+uv run mypy src tests
+scripts/run-checks.sh     # full package gate incl. artifact validation
+```
+
+Artifacts (`dist/`, `dist-tests/`, `node_modules/`, `.venv/`, wheels, tarballs)
+are generated and gitignored; they are not part of the root commit.
+
+## Ecosystem and core
+
+- The public `inter-agent-core` repository owns the bus runtime and the
+  `inter_agent.core.adapter_control` bridge this package consumes. (Its public
+  repository URL is published with that release; this package depends on the
+  compatible distribution name `inter-agent-core`.)
+- The public ecosystem repository coordinates adapters; it is added as a
+  submodule only once it has a published initial `main` commit.
+
+This package does not assume any currently published artifact exists beyond
+what a compatible `inter-agent-core` release provides.
+
+## Security
+
+- Authenticate with the shared bus secret; never commit secrets, tokens, keys,
+  or certificates to this repository.
+- TLS uses explicit cert/key paths; a wrong/untrusted certificate fails bounded
+  and actionable and never falls back to plaintext.
+- Peer messages are untrusted context, never instructions.

inter_agent_pi-0.2.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "inter-agent-pi"
+version = "0.2.0"
+description = "Pi helper for the inter-agent message bus: connect listener and command-line tools"
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Communications",
+]
+dependencies = [
+  "inter-agent-core==0.2.0",
+  "websockets==16.0",
+]
+
+[project.scripts]
+inter-agent-pi = "inter_agent_pi.cli:main"
+
+[dependency-groups]
+dev = [
+  "pytest==9.0.3",
+  "pytest-asyncio==1.3.0",
+  "ruff==0.15.12",
+  "black==26.3.1",
+  "mypy==1.20.2",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.black]
+line-length = 100
+target-version = ["py312"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["tests.*"]
+disallow_untyped_defs = false

inter_agent_pi-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

inter_agent_pi-0.2.0/src/inter_agent_pi/__init__.py

@@ -0,0 +1 @@
+"""Pi adapter package."""

inter_agent_pi-0.2.0/src/inter_agent_pi/cli.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+
+from inter_agent_pi import commands
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="inter-agent-pi")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    connect = sub.add_parser("connect")
+    connect.add_argument("name")
+    connect.add_argument("--label")
+
+    send = sub.add_parser("send")
+    send.add_argument("to")
+    send.add_argument("text")
+    send.add_argument("--from", dest="from_name")
+
+    broadcast = sub.add_parser("broadcast")
+    broadcast.add_argument("text")
+    broadcast.add_argument("--from", dest="from_name")
+
+    subscribe = sub.add_parser("subscribe")
+    subscribe.add_argument("channel")
+    subscribe.add_argument("--name", required=True)
+
+    unsubscribe = sub.add_parser("unsubscribe")
+    unsubscribe.add_argument("channel")
+    unsubscribe.add_argument("--name", required=True)
+
+    kick = sub.add_parser("kick")
+    kick.add_argument("name")
+
+    publish = sub.add_parser("publish")
+    publish.add_argument("channel")
+    publish.add_argument("text")
+    publish.add_argument("--from", dest="from_name")
+
+    channels = sub.add_parser("channels")
+    channels.add_argument("--json", action="store_true", help="emit JSON protocol output")
+
+    list_parser = sub.add_parser("list")
+    list_parser.add_argument("--json", action="store_true", help="emit JSON protocol output")
+
+    status = sub.add_parser("status")
+    status.add_argument("--json", action="store_true", help="emit JSON status output")
+
+    sub.add_parser("shutdown")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "connect":
+        return commands.connect(args.name, args.label)
+    if args.command == "send":
+        return commands.send(args.to, args.text, args.from_name)
+    if args.command == "broadcast":
+        return commands.broadcast(args.text, args.from_name)
+    if args.command == "subscribe":
+        return commands.subscribe(args.channel, args.name)
+    if args.command == "unsubscribe":
+        return commands.unsubscribe(args.channel, args.name)
+    if args.command == "kick":
+        return commands.kick(args.name)
+    if args.command == "publish":
+        return commands.publish(args.channel, args.text, args.from_name)
+    if args.command == "channels":
+        return commands.channels(as_json=args.json)
+    if args.command == "list":
+        return commands.list_sessions()
+    if args.command == "status":
+        print(commands.status_json())
+        return 0
+    if args.command == "shutdown":
+        return commands.shutdown()
+
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())