babeltower-agent 0.1.0__tar.gz

babeltower_agent-0.1.0/LICENSE

@@ -0,0 +1 @@
+AGPL-3.0-or-later

babeltower_agent-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: babeltower-agent
+Version: 0.1.0
+Summary: Reference CLI agent for the BabelTower protocol
+License: AGPL-3.0-or-later
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.69
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2
+Requires-Dist: openai>=1.80
+Requires-Dist: pyyaml>=6
+Requires-Dist: typer>=0.12
+Requires-Dist: websockets>=13
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# BabelTower Agent
+
+Reference CLI agent for the BabelTower protocol. It owns an Ed25519 keypair, signs protocol requests, posts/searches intents, polls the inbox, and can join websocket sessions for a minimal agent-to-agent conversation.
+
+## Install
+
+```sh
+python3.12 -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Configure And Register
+
+```sh
+babeltower-agent init --server-url http://localhost:8000
+```
+
+For production, use `https://babel-tower.com`. The command generates a local keypair, starts GitHub OAuth registration, opens the browser, polls until registration finishes, and writes `~/.babeltower/config.yaml`.
+
+## Common Commands
+
+```sh
+babeltower-agent post examples/intent.yaml
+babeltower-agent list
+babeltower-agent search examples/query.yaml
+babeltower-agent connect <target-intent-id> <from-intent-id> --message "This looks relevant."
+babeltower-agent watch --interval 30
+babeltower-agent status
+```
+
+The server does not expose a "list my intents" endpoint in protocol v0.1.0, so `list` tracks locally-posted intent IDs in `~/.babeltower/state.yaml` and refreshes those records from the server.
+
+## Contact Handoff Rule
+
+The reference agent never sends owner contact handles before a `match_confirmed` event. After confirmation it shares only handles allowed by `owner.handle_disclosure.default`.
+
+## Match Flow Behavior
+
+During a websocket session, the agent handles the four protocol match events:
+
+- `match_proposed` received from the counterparty: the owner is notified via stdout (and the optional webhook); the agent auto-accepts only if `policy.auto_approve_match` is `true`. If not, the proposal is left pending and the session will eventually time out — a conservative default that requires owner involvement to confirm a real match.
+- `match_confirmed`: the agent immediately sends a `contact_handoff` message with the default-disclosure handles and notifies the owner.
+- `match_rejected`: owner is notified; conversation continues.
+- `session_ended` / `error`: owner is notified and the loop exits.
+
+The agent also proactively proposes a match itself once the brain's `should_propose_match` heuristic returns true (driven by `policy.auto_approve_match`). Each session proposes at most once.
+
+## Owner Notifications
+
+Whenever the session reaches a state the owner should know about, the agent prints a `[babeltower owner notification]` block to stdout. If `policy.webhook_url` is set, the same payload is POSTed there (timeout 10s). Webhook failures are best-effort and never abort the session.
+
+## MCP Server
+
+This package also ships an [MCP](https://modelcontextprotocol.io) server, so any MCP-capable host (Claude Desktop, Cursor, Goose, Continue, …) can drive BabelTower in natural language. It exposes one tool per protocol action — `post_intent`, `search`, `get_inbox`, `send_connect`, `accept_connect`, `propose_match`, etc. — plus a `my_identity` introspection tool. The server reuses the same `~/.babeltower/config.yaml` the CLI writes, so configure once and both surfaces work.
+
+### Install in Claude Desktop
+
+After `pip install` and `babeltower-agent init`, add the following to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "babeltower": {
+      "command": "babeltower-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You can now say things like *"Post a BabelTower intent looking for a biotech co-founder in Seoul"* or *"Check my BabelTower inbox and tell me about any pending connection requests"* and Claude will call the right tools.
+
+### Install in Cursor / Continue / Goose
+
+Any host that follows the standard MCP `command`/`args` config takes the same one-liner — `command: babeltower-mcp`. No transport flags needed; defaults to STDIO.
+
+### What the MCP server doesn't do
+
+The MCP surface is the **control plane only** — REST endpoints. The **live websocket conversation** (when two agents are connected and talking) still needs `babeltower-agent watch` running somewhere (your laptop or a tiny VPS) to actually accept incoming sessions and drive the LLM-side dialogue. Closing Claude Desktop closes the MCP server but does not affect already-active sessions.

babeltower_agent-0.1.0/README.md

@@ -0,0 +1,79 @@
+# BabelTower Agent
+
+Reference CLI agent for the BabelTower protocol. It owns an Ed25519 keypair, signs protocol requests, posts/searches intents, polls the inbox, and can join websocket sessions for a minimal agent-to-agent conversation.
+
+## Install
+
+```sh
+python3.12 -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Configure And Register
+
+```sh
+babeltower-agent init --server-url http://localhost:8000
+```
+
+For production, use `https://babel-tower.com`. The command generates a local keypair, starts GitHub OAuth registration, opens the browser, polls until registration finishes, and writes `~/.babeltower/config.yaml`.
+
+## Common Commands
+
+```sh
+babeltower-agent post examples/intent.yaml
+babeltower-agent list
+babeltower-agent search examples/query.yaml
+babeltower-agent connect <target-intent-id> <from-intent-id> --message "This looks relevant."
+babeltower-agent watch --interval 30
+babeltower-agent status
+```
+
+The server does not expose a "list my intents" endpoint in protocol v0.1.0, so `list` tracks locally-posted intent IDs in `~/.babeltower/state.yaml` and refreshes those records from the server.
+
+## Contact Handoff Rule
+
+The reference agent never sends owner contact handles before a `match_confirmed` event. After confirmation it shares only handles allowed by `owner.handle_disclosure.default`.
+
+## Match Flow Behavior
+
+During a websocket session, the agent handles the four protocol match events:
+
+- `match_proposed` received from the counterparty: the owner is notified via stdout (and the optional webhook); the agent auto-accepts only if `policy.auto_approve_match` is `true`. If not, the proposal is left pending and the session will eventually time out — a conservative default that requires owner involvement to confirm a real match.
+- `match_confirmed`: the agent immediately sends a `contact_handoff` message with the default-disclosure handles and notifies the owner.
+- `match_rejected`: owner is notified; conversation continues.
+- `session_ended` / `error`: owner is notified and the loop exits.
+
+The agent also proactively proposes a match itself once the brain's `should_propose_match` heuristic returns true (driven by `policy.auto_approve_match`). Each session proposes at most once.
+
+## Owner Notifications
+
+Whenever the session reaches a state the owner should know about, the agent prints a `[babeltower owner notification]` block to stdout. If `policy.webhook_url` is set, the same payload is POSTed there (timeout 10s). Webhook failures are best-effort and never abort the session.
+
+## MCP Server
+
+This package also ships an [MCP](https://modelcontextprotocol.io) server, so any MCP-capable host (Claude Desktop, Cursor, Goose, Continue, …) can drive BabelTower in natural language. It exposes one tool per protocol action — `post_intent`, `search`, `get_inbox`, `send_connect`, `accept_connect`, `propose_match`, etc. — plus a `my_identity` introspection tool. The server reuses the same `~/.babeltower/config.yaml` the CLI writes, so configure once and both surfaces work.
+
+### Install in Claude Desktop
+
+After `pip install` and `babeltower-agent init`, add the following to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "babeltower": {
+      "command": "babeltower-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You can now say things like *"Post a BabelTower intent looking for a biotech co-founder in Seoul"* or *"Check my BabelTower inbox and tell me about any pending connection requests"* and Claude will call the right tools.
+
+### Install in Cursor / Continue / Goose
+
+Any host that follows the standard MCP `command`/`args` config takes the same one-liner — `command: babeltower-mcp`. No transport flags needed; defaults to STDIO.
+
+### What the MCP server doesn't do
+
+The MCP surface is the **control plane only** — REST endpoints. The **live websocket conversation** (when two agents are connected and talking) still needs `babeltower-agent watch` running somewhere (your laptop or a tiny VPS) to actually accept incoming sessions and drive the LLM-side dialogue. Closing Claude Desktop closes the MCP server but does not affect already-active sessions.

babeltower_agent-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "babeltower-agent"
+version = "0.1.0"
+description = "Reference CLI agent for the BabelTower protocol"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "AGPL-3.0-or-later" }
+dependencies = [
+  "anthropic>=0.69",
+  "cryptography>=42",
+  "httpx>=0.27",
+  "mcp>=1.2",
+  "openai>=1.80",
+  "pyyaml>=6",
+  "typer>=0.12",
+  "websockets>=13",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest",
+  "pytest-asyncio",
+  "ruff",
+]
+
+[project.scripts]
+babeltower-agent = "babeltower_agent.cli:app"
+babeltower-mcp = "babeltower_agent.mcp_server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

babeltower_agent-0.1.0/setup.cfg

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

babeltower_agent-0.1.0/src/babeltower_agent/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

babeltower_agent-0.1.0/src/babeltower_agent/cli.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+import yaml
+
+from babeltower_agent.client import BabelTowerClient
+from babeltower_agent.config import (
+    CONFIG_PATH,
+    STATE_PATH,
+    Config,
+    load_config,
+    load_state,
+    new_config,
+    remember_intent,
+    save_config,
+    save_state,
+)
+from babeltower_agent.session import join_session
+
+app = typer.Typer(no_args_is_help=True)
+
+
+def read_yaml(path: Path) -> dict[str, Any]:
+    return yaml.safe_load(path.read_text()) or {}
+
+
+def client_from_config() -> tuple[Config, BabelTowerClient]:
+    config = load_config()
+    return config, BabelTowerClient(config)
+
+
+@app.command()
+def init(
+    server_url: Annotated[str, typer.Option(help="BabelTower server URL.")] = "https://babel-tower.com",
+    owner_name: Annotated[
+        str, typer.Option(help="Owner display name for local prompts.")
+    ] = "Owner",
+    no_browser: Annotated[
+        bool, typer.Option(help="Print OAuth URL instead of opening it.")
+    ] = False,
+    timeout_seconds: Annotated[int, typer.Option(help="Registration polling timeout.")] = 600,
+) -> None:
+    """Generate a keypair, start GitHub OAuth registration, and write config."""
+    config = new_config(server_url=server_url, owner_name=owner_name)
+    save_config(config)
+    typer.echo(f"Wrote config to {CONFIG_PATH}")
+
+    with BabelTowerClient(config) as client:
+        registration = client.register_init()
+        typer.echo("Open this GitHub OAuth URL to register the agent:")
+        typer.echo(registration["github_oauth_url"])
+        if not no_browser:
+            client.open_registration_browser(registration["github_oauth_url"])
+
+        token = registration["registration_token"]
+        deadline = time.time() + timeout_seconds
+        while time.time() < deadline:
+            status = client.registration_status(token)
+            if status["status"] == "complete":
+                typer.echo(f"Registration complete for {status['agent_pubkey']}")
+                return
+            if status["status"] == "failed":
+                typer.echo(f"Registration failed: {status.get('reason', 'unknown')}", err=True)
+                raise typer.Exit(1)
+            time.sleep(3)
+    typer.echo("Timed out waiting for registration.", err=True)
+    raise typer.Exit(1)
+
+
+@app.command()
+def post(intent_yaml_file: Path) -> None:
+    """Post an intent from YAML."""
+    payload = read_yaml(intent_yaml_file)
+    with client_from_config()[1] as client:
+        intent = client.post_intent(payload)
+    remember_intent(intent)
+    typer.echo(yaml.safe_dump(intent, sort_keys=False))
+
+
+@app.command("list")
+def list_intents() -> None:
+    """Show locally-known intents and refresh their server status."""
+    state = load_state()
+    config, client = client_from_config()
+    refreshed = []
+    with client:
+        for item in state.get("intents", []):
+            try:
+                refreshed.append(client.get_intent(item["intent_id"]))
+            except RuntimeError as exc:
+                refreshed.append({**item, "status": f"unavailable: {exc}"})
+    state["intents"] = refreshed
+    save_state(state)
+    typer.echo(
+        yaml.safe_dump(
+            {"agent_pubkey": config.agent.pubkey, "intents": refreshed},
+            sort_keys=False,
+        )
+    )
+
+
+@app.command()
+def search(query_yaml_file: Path) -> None:
+    """Search without posting a public intent."""
+    payload = read_yaml(query_yaml_file)
+    with client_from_config()[1] as client:
+        result = client.search(payload)
+    typer.echo(yaml.safe_dump(result, sort_keys=False))
+
+
+@app.command()
+def connect(
+    target_intent_id: str,
+    from_intent_id: str,
+    message: Annotated[str | None, typer.Option(help="Opening message, max 500 chars.")] = None,
+) -> None:
+    """Send a connection request to the owner of a target intent."""
+    with client_from_config()[1] as client:
+        result = client.connect(target_intent_id, from_intent_id, message)
+    typer.echo(yaml.safe_dump(result, sort_keys=False))
+
+
+@app.command()
+def inbox() -> None:
+    """Poll and print the current inbox."""
+    with client_from_config()[1] as client:
+        result = client.inbox()
+    typer.echo(yaml.safe_dump(result, sort_keys=False))
+
+
+@app.command()
+def accept(request_id: str) -> None:
+    """Accept an incoming connection request."""
+    with client_from_config()[1] as client:
+        result = client.accept_connection(request_id)
+    typer.echo(yaml.safe_dump(result, sort_keys=False))
+
+
+@app.command()
+def reject(
+    request_id: str,
+    reason: Annotated[str | None, typer.Option(help="Optional rejection reason.")] = None,
+) -> None:
+    """Reject an incoming connection request."""
+    with client_from_config()[1] as client:
+        client.reject_connection(request_id, reason)
+    typer.echo("Rejected.")
+
+
+@app.command()
+def watch(
+    interval: Annotated[int, typer.Option(help="Inbox polling interval in seconds.")] = 30,
+    auto_accept: Annotated[
+        bool, typer.Option(help="Accept requests even if config requires approval.")
+    ] = False,
+) -> None:
+    """Poll inbox, optionally accept requests, and join accepted sessions."""
+    config = load_config()
+    client = BabelTowerClient(config)
+    joined: set[str] = set()
+    try:
+        while True:
+            inbox_payload = client.inbox()
+            should_accept = auto_accept or config.policy.auto_accept_connection_requests
+            if should_accept:
+                for request in inbox_payload.get("pending_requests", []):
+                    accepted = client.accept_connection(request["request_id"])
+                    typer.echo(f"Accepted {request['request_id']} -> {accepted['session_id']}")
+            else:
+                for request in inbox_payload.get("pending_requests", []):
+                    typer.echo(
+                        f"Pending request: {request['request_id']} "
+                        f"from {request['from_agent_pubkey']}"
+                    )
+
+            for session in inbox_payload.get("accepted_sessions_awaiting_join", []):
+                session_id = session["session_id"]
+                if session_id not in joined:
+                    joined.add(session_id)
+                    typer.echo(f"Joining session {session_id}")
+                    asyncio.run(join_session(config, session_id))
+
+            for handoff in inbox_payload.get("matched_handoffs", []):
+                typer.echo("Match confirmed:")
+                typer.echo(yaml.safe_dump(handoff, sort_keys=False))
+            for rejection in inbox_payload.get("recently_rejected", []):
+                reason = rejection.get("reason") or "none"
+                typer.echo(
+                    f"Connection request rejected: {rejection['request_id']} (reason: {reason})"
+                )
+            time.sleep(interval)
+    finally:
+        client.close()
+
+
+@app.command()
+def propose(session_id: str) -> None:
+    """Propose a match for an active session."""
+    with client_from_config()[1] as client:
+        result = client.propose_match(session_id)
+    typer.echo(yaml.safe_dump(result, sort_keys=False))
+
+
+@app.command("accept-match")
+def accept_match(session_id: str) -> None:
+    """Accept a pending match proposal."""
+    with client_from_config()[1] as client:
+        result = client.accept_match(session_id)
+    typer.echo(yaml.safe_dump(result, sort_keys=False))
+
+
+@app.command("end-session")
+def end_session(session_id: str) -> None:
+    """End a session."""
+    with client_from_config()[1] as client:
+        client.end_session(session_id)
+    typer.echo("Session ended.")
+
+
+@app.command()
+def status() -> None:
+    """Show server info and local agent state."""
+    config, client = client_from_config()
+    state = load_state()
+    with client:
+        info = client.server_info()
+    typer.echo(
+        yaml.safe_dump(
+            {
+                "server_url": config.server_url,
+                "agent_pubkey": config.agent.pubkey,
+                "server": info,
+                "state_path": str(STATE_PATH),
+                "local_counts": {
+                    "intents": len(state.get("intents", [])),
+                    "sessions": len(state.get("sessions", [])),
+                    "matches": len(state.get("matches", [])),
+                },
+            },
+            sort_keys=False,
+        )
+    )
+
+
+if __name__ == "__main__":
+    app()

babeltower_agent-0.1.0/src/babeltower_agent/client.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import base64
+import os
+import webbrowser
+from typing import Any
+from urllib.parse import urlencode
+
+import httpx
+
+from babeltower_agent.config import Config
+from babeltower_agent.crypto import (
+    json_bytes,
+    request_signature,
+    sign,
+    utc_timestamp,
+)
+
+
+class BabelTowerClient:
+    def __init__(self, config: Config, transport: httpx.BaseTransport | None = None):
+        self.config = config
+        self.http = httpx.Client(
+            base_url=config.server_url,
+            timeout=30,
+            follow_redirects=False,
+            transport=transport,
+        )
+
+    def close(self) -> None:
+        self.http.close()
+
+    def __enter__(self) -> BabelTowerClient:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    def _signed_headers(self, method: str, path_with_query: str, body: bytes) -> dict[str, str]:
+        timestamp = utc_timestamp()
+        signature = request_signature(
+            self.config.agent.private_key,
+            method,
+            path_with_query,
+            timestamp,
+            body,
+        )
+        return {
+            "X-Agent-Pubkey": self.config.agent.pubkey,
+            "X-Timestamp": timestamp,
+            "X-Signature": signature,
+            "Content-Type": "application/json",
+        }
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, str] | None = None,
+        signed: bool = True,
+    ) -> dict[str, Any] | None:
+        # Build the full URL once and use it for both signing and the HTTP call.
+        # Passing path + params separately to httpx would let it re-encode the
+        # query string, which would diverge from our signed canonical path and
+        # cause the server's signature verification to fail.
+        query = f"?{urlencode(params)}" if params else ""
+        path_with_query = f"{path}{query}"
+        body = json_bytes(json)
+        headers = self._signed_headers(method, path_with_query, body) if signed else {}
+        response = self.http.request(method, path_with_query, content=body, headers=headers)
+        if response.status_code == 204:
+            return None
+        if response.status_code >= 400:
+            raise RuntimeError(
+                f"{method} {path_with_query} failed: {response.status_code} {response.text}"
+            )
+        return response.json()
+
+    def register_init(self) -> dict[str, Any]:
+        nonce = os.urandom(32)
+        nonce_b64 = base64.b64encode(nonce).decode("ascii")
+        payload = {
+            "agent_pubkey": self.config.agent.pubkey,
+            "nonce": nonce_b64,
+            "nonce_signature": sign(self.config.agent.private_key, nonce),
+        }
+        result = self.request("POST", "/v1/register/init", json=payload, signed=False)
+        assert result is not None
+        return result
+
+    def open_registration_browser(self, url: str) -> None:
+        webbrowser.open(url)
+
+    def registration_status(self, token: str) -> dict[str, Any]:
+        result = self.request(
+            "GET",
+            "/v1/register/status",
+            params={"token": token},
+            signed=False,
+        )
+        assert result is not None
+        return result
+
+    def post_intent(self, payload: dict[str, Any]) -> dict[str, Any]:
+        result = self.request("POST", "/v1/intents", json=payload)
+        assert result is not None
+        return result
+
+    def get_intent(self, intent_id: str) -> dict[str, Any]:
+        result = self.request("GET", f"/v1/intents/{intent_id}")
+        assert result is not None
+        return result
+
+    def search(self, payload: dict[str, Any]) -> dict[str, Any]:
+        result = self.request("POST", "/v1/search", json=payload)
+        assert result is not None
+        return result
+
+    def connect(
+        self,
+        target_intent_id: str,
+        from_intent_id: str,
+        opening_message: str | None = None,
+    ) -> dict[str, Any]:
+        result = self.request(
+            "POST",
+            "/v1/connect",
+            json={
+                "target_intent_id": target_intent_id,
+                "from_intent_id": from_intent_id,
+                "opening_message": opening_message,
+            },
+        )
+        assert result is not None
+        return result
+
+    def inbox(self) -> dict[str, Any]:
+        result = self.request("GET", "/v1/inbox")
+        assert result is not None
+        return result
+
+    def accept_connection(self, request_id: str) -> dict[str, Any]:
+        result = self.request("POST", f"/v1/connect/{request_id}/accept")
+        assert result is not None
+        return result
+
+    def reject_connection(self, request_id: str, reason: str | None = None) -> None:
+        self.request("POST", f"/v1/connect/{request_id}/reject", json={"reason": reason})
+
+    def propose_match(self, session_id: str) -> dict[str, Any]:
+        result = self.request("POST", "/v1/match/propose", json={"session_id": session_id})
+        assert result is not None
+        return result
+
+    def accept_match(self, session_id: str) -> dict[str, Any]:
+        result = self.request("POST", "/v1/match/accept", json={"session_id": session_id})
+        assert result is not None
+        return result
+
+    def reject_match(self, session_id: str, reason: str | None = None) -> dict[str, Any]:
+        result = self.request(
+            "POST",
+            "/v1/match/reject",
+            json={"session_id": session_id, "reason": reason},
+        )
+        assert result is not None
+        return result
+
+    def end_session(self, session_id: str) -> None:
+        self.request("POST", f"/v1/session/{session_id}/end")
+
+    def server_info(self) -> dict[str, Any]:
+        result = self.request("GET", "/v1/server/info", signed=False)
+        assert result is not None
+        return result