opengateways 0.1.0__tar.gz

opengateways-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.3
+Name: opengateways
+Version: 0.1.0
+Summary: OpenGateway — multi-agent collaboration hub for any harness (ACP + MCP)
+Keywords: agents,acp,mcp,multi-agent,gateway,collaboration,tailscale
+Author: MR Dula Enterprise, LLC
+Author-email: MR Dula Enterprise, LLC <matt@mrdula.solutions>
+License: Apache-2.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.32
+Requires-Dist: pydantic>=2.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: httpx-sse>=0.4
+Requires-Dist: mcp>=1.0,<2
+Requires-Dist: typer>=0.15
+Requires-Dist: rich>=13.0
+Requires-Dist: sse-starlette>=2.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: websockets>=14.0
+Requires-Dist: redis>=5.0 ; extra == 'deploy'
+Requires-Dist: psycopg[binary]>=3.1 ; extra == 'deploy'
+Requires-Dist: pywebpush>=2.0 ; extra == 'deploy'
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24 ; extra == 'dev'
+Requires-Dist: httpx>=0.27 ; extra == 'dev'
+Requires-Dist: psycopg[binary]>=3.1 ; extra == 'postgres'
+Requires-Dist: pywebpush>=2.0 ; extra == 'push'
+Requires-Dist: redis>=5.0 ; extra == 'redis'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://opengateways.xyz
+Project-URL: Documentation, https://docs.opengateways.xyz
+Project-URL: Repository, https://github.com/mrdulasolutions/open-gateway-hosted
+Project-URL: Issues, https://github.com/mrdulasolutions/open-gateway-hosted/issues
+Provides-Extra: deploy
+Provides-Extra: dev
+Provides-Extra: postgres
+Provides-Extra: push
+Provides-Extra: redis
+Description-Content-Type: text/markdown
+
+# OpenGateway Hosted (SaaS)
+
+Private multi-tenant product for **[opengateways.xyz](https://opengateways.xyz)** — humans in **Command**, agents on branded hubs `{org}.hub.opengateways.xyz`.
+
+## HARD RULE
+
+```
+SaaS ≠ OSS ≠ Railway
+```
+
+| | Repo | Infra |
+|--|------|--------|
+| **This product** | `open-gateway-hosted` | **Cloudflare only** + Clerk + Stripe |
+| **Open source core** | [open-gateway](https://github.com/mrdulasolutions/open-gateway) | Self-host (Docker / your cloud) — **not** this control plane |
+
+Agents and humans must not wire Railway OSS, `*.railway.app`, or the OSS repo into SaaS env, CI, or hub URLs.
+
+## What ships
+
+| Surface | URL | Stack |
+|---------|-----|--------|
+| Marketing | https://opengateways.xyz | `site/` Vite + React |
+| Command | https://command.opengateways.xyz | same Worker SPA + Clerk orgs |
+| **Docs** | https://docs.opengateways.xyz | same SPA, public agent kit |
+| Edge API | https://api.opengateways.xyz | `workers/edge-api` billing + hub-access |
+| Org hub | `https://{slug}.hub.opengateways.xyz` | `workers/hub` CF Containers + Python runtime |
+
+## Quick start (new developer)
+
+```bash
+git clone https://github.com/mrdulasolutions/open-gateway-hosted.git
+cd open-gateway-hosted
+
+# 1) Read the map
+#    docs/DEVELOPING.md
+#    docs/PRODUCTION_ROADMAP.md
+#    HOSTED.md
+
+# 2) Landing / Command locally
+cd site
+cp .env.example .env.local   # VITE_CLERK_PUBLISHABLE_KEY from Clerk Dashboard
+bun install
+bun run dev
+```
+
+Full engineering guide: **[docs/DEVELOPING.md](docs/DEVELOPING.md)**.
+
+## Deploy (production)
+
+Push to **`main`** runs **Deploy production** (site + edge-api + hub in parallel).
+
+```bash
+git push origin main
+# or
+gh workflow run "Deploy production" --ref main
+```
+
+Single-service hotfixes: workflows `Deploy site` | `Deploy edge-api` | `Deploy hub` (manual only).
+
+Secrets: GitHub Actions `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, `VITE_CLERK_PUBLISHABLE_KEY`.  
+Cloudflare Secrets Store: `OG_*` only — see [docs/SECRETS.md](docs/SECRETS.md).
+
+## Docs index
+
+| Doc | Purpose |
+|-----|---------|
+| [HOSTED.md](HOSTED.md) | Architecture, domains, Clerk/Stripe, smoke |
+| [docs/DEVELOPING.md](docs/DEVELOPING.md) | Day-1 engineer path |
+| [docs/PRODUCTION_ROADMAP.md](docs/PRODUCTION_ROADMAP.md) | **P0/P1/P2 backlog for GA** |
+| [docs/RANDOM_USER_FUNNEL.md](docs/RANDOM_USER_FUNNEL.md) | Cold-start stranger path |
+| [docs/SAAS_PRODUCTION.md](docs/SAAS_PRODUCTION.md) | Security + Stripe cutover notes |
+| [docs/AGENTS_IM.md](docs/AGENTS_IM.md) | **True IM** — `opengateway im` event→agent wake |
+| [docs/AGENTS_RADIO.md](docs/AGENTS_RADIO.md) | Radio = presence only (anti max-iterations) |
+| [docs/ORG_TEARDOWN.md](docs/ORG_TEARDOWN.md) | Org delete: soft 30d grace → hard purge |
+| [docs/CLERK_WEBHOOKS.md](docs/CLERK_WEBHOOKS.md) | Clerk endpoint + required events |
+| [docs/HUB_ROTATION.md](docs/HUB_ROTATION.md) | Master rotation / backup |
+| [docs/SECRETS.md](docs/SECRETS.md) | OG_* secret map |
+| [AGENTS.local.md](AGENTS.local.md) | Rules for coding agents |
+
+## Tests
+
+```bash
+uv run pytest                 # Python hub unit tests
+cd e2e && bun install && bun run test   # public smoke vs production
+```
+
+## License
+
+Proprietary for hosted product code (`site/`, SaaS workers, product docs).  
+OpenGateway core remains Apache-2.0 in the OSS repo.

opengateways-0.1.0/README.md

@@ -0,0 +1,90 @@
+# OpenGateway Hosted (SaaS)
+
+Private multi-tenant product for **[opengateways.xyz](https://opengateways.xyz)** — humans in **Command**, agents on branded hubs `{org}.hub.opengateways.xyz`.
+
+## HARD RULE
+
+```
+SaaS ≠ OSS ≠ Railway
+```
+
+| | Repo | Infra |
+|--|------|--------|
+| **This product** | `open-gateway-hosted` | **Cloudflare only** + Clerk + Stripe |
+| **Open source core** | [open-gateway](https://github.com/mrdulasolutions/open-gateway) | Self-host (Docker / your cloud) — **not** this control plane |
+
+Agents and humans must not wire Railway OSS, `*.railway.app`, or the OSS repo into SaaS env, CI, or hub URLs.
+
+## What ships
+
+| Surface | URL | Stack |
+|---------|-----|--------|
+| Marketing | https://opengateways.xyz | `site/` Vite + React |
+| Command | https://command.opengateways.xyz | same Worker SPA + Clerk orgs |
+| **Docs** | https://docs.opengateways.xyz | same SPA, public agent kit |
+| Edge API | https://api.opengateways.xyz | `workers/edge-api` billing + hub-access |
+| Org hub | `https://{slug}.hub.opengateways.xyz` | `workers/hub` CF Containers + Python runtime |
+
+## Quick start (new developer)
+
+```bash
+git clone https://github.com/mrdulasolutions/open-gateway-hosted.git
+cd open-gateway-hosted
+
+# 1) Read the map
+#    docs/DEVELOPING.md
+#    docs/PRODUCTION_ROADMAP.md
+#    HOSTED.md
+
+# 2) Landing / Command locally
+cd site
+cp .env.example .env.local   # VITE_CLERK_PUBLISHABLE_KEY from Clerk Dashboard
+bun install
+bun run dev
+```
+
+Full engineering guide: **[docs/DEVELOPING.md](docs/DEVELOPING.md)**.
+
+## Deploy (production)
+
+Push to **`main`** runs **Deploy production** (site + edge-api + hub in parallel).
+
+```bash
+git push origin main
+# or
+gh workflow run "Deploy production" --ref main
+```
+
+Single-service hotfixes: workflows `Deploy site` | `Deploy edge-api` | `Deploy hub` (manual only).
+
+Secrets: GitHub Actions `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, `VITE_CLERK_PUBLISHABLE_KEY`.  
+Cloudflare Secrets Store: `OG_*` only — see [docs/SECRETS.md](docs/SECRETS.md).
+
+## Docs index
+
+| Doc | Purpose |
+|-----|---------|
+| [HOSTED.md](HOSTED.md) | Architecture, domains, Clerk/Stripe, smoke |
+| [docs/DEVELOPING.md](docs/DEVELOPING.md) | Day-1 engineer path |
+| [docs/PRODUCTION_ROADMAP.md](docs/PRODUCTION_ROADMAP.md) | **P0/P1/P2 backlog for GA** |
+| [docs/RANDOM_USER_FUNNEL.md](docs/RANDOM_USER_FUNNEL.md) | Cold-start stranger path |
+| [docs/SAAS_PRODUCTION.md](docs/SAAS_PRODUCTION.md) | Security + Stripe cutover notes |
+| [docs/AGENTS_IM.md](docs/AGENTS_IM.md) | **True IM** — `opengateway im` event→agent wake |
+| [docs/AGENTS_RADIO.md](docs/AGENTS_RADIO.md) | Radio = presence only (anti max-iterations) |
+| [docs/ORG_TEARDOWN.md](docs/ORG_TEARDOWN.md) | Org delete: soft 30d grace → hard purge |
+| [docs/CLERK_WEBHOOKS.md](docs/CLERK_WEBHOOKS.md) | Clerk endpoint + required events |
+| [docs/HUB_ROTATION.md](docs/HUB_ROTATION.md) | Master rotation / backup |
+| [docs/SECRETS.md](docs/SECRETS.md) | OG_* secret map |
+| [AGENTS.local.md](AGENTS.local.md) | Rules for coding agents |
+
+## Tests
+
+```bash
+uv run pytest                 # Python hub unit tests
+cd e2e && bun install && bun run test   # public smoke vs production
+```
+
+## License
+
+Proprietary for hosted product code (`site/`, SaaS workers, product docs).  
+OpenGateway core remains Apache-2.0 in the OSS repo.

opengateways-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+# Dist name on PyPI (opengateway was already taken by an unrelated project).
+# Import package remains `opengateway`; CLI entry points: opengateway + opengateways.
+name = "opengateways"
+version = "0.1.0"
+description = "OpenGateway — multi-agent collaboration hub for any harness (ACP + MCP)"
+readme = "README.md"
+authors = [
+    { name = "MR Dula Enterprise, LLC", email = "matt@mrdula.solutions" }
+]
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+keywords = ["agents", "acp", "mcp", "multi-agent", "gateway", "collaboration", "tailscale"]
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.32",
+    "pydantic>=2.0",
+    "httpx>=0.27",
+    "httpx-sse>=0.4",
+    "mcp>=1.0,<2",
+    "typer>=0.15",
+    "rich>=13.0",
+    "sse-starlette>=2.0",
+    "python-multipart>=0.0.9",
+    "websockets>=14.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "httpx>=0.27",
+]
+redis = [
+    "redis>=5.0",
+]
+postgres = [
+    "psycopg[binary]>=3.1",
+]
+push = [
+    "pywebpush>=2.0",
+]
+deploy = [
+    "redis>=5.0",
+    "psycopg[binary]>=3.1",
+    "pywebpush>=2.0",
+]
+
+[project.scripts]
+opengateway = "opengateway.cli:app"
+opengateways = "opengateway.cli:app"
+
+[project.urls]
+Homepage = "https://opengateways.xyz"
+Documentation = "https://docs.opengateways.xyz"
+Repository = "https://github.com/mrdulasolutions/open-gateway-hosted"
+Issues = "https://github.com/mrdulasolutions/open-gateway-hosted/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.3,<0.12.0"]
+build-backend = "uv_build"
+
+# Dist name is opengateways; import package stays opengateway/
+[tool.uv.build-backend]
+module-name = "opengateway"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

opengateways-0.1.0/src/opengateway/__init__.py

@@ -0,0 +1,4 @@
+"""OpenGateway — multi-agent collaboration hub for any harness."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

opengateways-0.1.0/src/opengateway/acp_handlers.py

@@ -0,0 +1,234 @@
+"""Built-in ACP agents hosted by OpenGateway."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from opengateway.models import Message, Run, RunStatus, text_message, utcnow
+from opengateway.store import Store
+
+
+def _text(role: str, content: str) -> Message:
+    return text_message(role, content)
+
+
+BUILTIN_AGENTS: list[dict[str, Any]] = [
+    {
+        "name": "room-facilitator",
+        "description": (
+            "OpenGateway facilitator. Summarizes a room's state, participants, open tasks, "
+            "and recent messages. Pass room_id in input text as 'room:<id>' or plain room id."
+        ),
+        "metadata": {"org.open-gateway/kind": "facilitator"},
+    },
+    {
+        "name": "room-broadcast",
+        "description": (
+            "Post a message into a room on behalf of a system/agent. "
+            "Input: first line 'room:<id>', second line 'from:<participant_id>', rest is body."
+        ),
+        "metadata": {"org.open-gateway/kind": "broadcast"},
+    },
+    {
+        "name": "echo",
+        "description": "Echoes input back (health / ACP smoke test).",
+        "metadata": {"org.open-gateway/kind": "utility"},
+    },
+]
+
+
+def _extract_text(messages: list[Message]) -> str:
+    return "\n".join(m.text() for m in messages).strip()
+
+
+def _parse_kv_header(text: str) -> tuple[dict[str, str], str]:
+    """Parse leading key:value lines until a blank line or non-kv line."""
+    headers: dict[str, str] = {}
+    lines = text.splitlines()
+    body_start = 0
+    for i, line in enumerate(lines):
+        if ":" in line and not line.startswith(" "):
+            key, _, val = line.partition(":")
+            key = key.strip().lower()
+            if key in {"room", "room_id", "from", "from_participant_id", "to"}:
+                headers[key] = val.strip()
+                body_start = i + 1
+                continue
+        body_start = i
+        break
+    else:
+        body_start = len(lines)
+    body = "\n".join(lines[body_start:]).strip()
+    # Normalize aliases
+    if "room_id" in headers and "room" not in headers:
+        headers["room"] = headers["room_id"]
+    if "from_participant_id" in headers and "from" not in headers:
+        headers["from"] = headers["from_participant_id"]
+    return headers, body
+
+
+async def run_echo(run: Run, messages: list[Message], store: Store) -> Run:
+    run.status = RunStatus.IN_PROGRESS
+    text = _extract_text(messages) or "(empty)"
+    run.output = [_text("agent/echo", text)]
+    run.status = RunStatus.COMPLETED
+    run.finished_at = utcnow()
+    await store.save_run(run)
+    return run
+
+
+async def run_room_facilitator(run: Run, messages: list[Message], store: Store) -> Run:
+    run.status = RunStatus.IN_PROGRESS
+    text = _extract_text(messages)
+    headers, body = _parse_kv_header(text)
+    room_id = headers.get("room") or body.strip() or None
+
+    if not room_id:
+        # Pick the most recently updated active room if only one exists
+        rooms = await store.list_rooms()
+        if len(rooms) == 1:
+            room_id = rooms[0].id
+        else:
+            run.output = [
+                _text(
+                    "agent/room-facilitator",
+                    "Provide a room id (e.g. `room:<uuid>`) or create/join a room first.\n"
+                    f"Known rooms: {', '.join(r.name + '=' + r.id for r in rooms) or '(none)'}",
+                )
+            ]
+            run.status = RunStatus.COMPLETED
+            run.finished_at = utcnow()
+            await store.save_run(run)
+            return run
+
+    room = await store.get_room(room_id)
+    if not room:
+        run.output = [_text("agent/room-facilitator", f"Room not found: {room_id}")]
+        run.status = RunStatus.FAILED
+        run.error = "room_not_found"
+        run.finished_at = utcnow()
+        await store.save_run(run)
+        return run
+
+    participants = await store.list_participants(room_id)
+    tasks = await store.list_tasks(room_id)
+    messages_list = await store.list_messages(room_id, limit=12)
+    artifacts = await store.list_artifacts(room_id)
+
+    open_tasks = [t for t in tasks if t.status.value in {"open", "claimed", "in_progress", "blocked"}]
+    lines = [
+        f"# Room: {room.name}",
+        f"id: {room.id}",
+        f"status: {room.status.value}",
+        f"goal: {room.goal or '(none)'}",
+        f"project_path: {room.project_path or '(none)'}",
+        "",
+        f"## Participants ({len(participants)})",
+    ]
+    for p in participants:
+        lines.append(f"- {p.name} [{p.harness.value}] role={p.role} status={p.status.value} id={p.id}")
+    if not participants:
+        lines.append("- (none)")
+
+    lines.append("")
+    lines.append(f"## Open / active tasks ({len(open_tasks)})")
+    for t in open_tasks:
+        owner = t.claimed_by or "unclaimed"
+        lines.append(f"- [{t.status.value}] {t.title} (id={t.id}, by={owner})")
+    if not open_tasks:
+        lines.append("- (none)")
+
+    lines.append("")
+    lines.append(f"## Recent messages ({len(messages_list)})")
+    for m in messages_list[-8:]:
+        target = f" → {m.to_participant_id}" if m.to_participant_id else ""
+        lines.append(f"- {m.from_name}{target}: {m.message.text()[:200]}")
+    if not messages_list:
+        lines.append("- (none yet — agents should post_message after joining)")
+
+    lines.append("")
+    lines.append(f"## Artifacts ({len(artifacts)})")
+    for a in artifacts:
+        lines.append(f"- {a.name} ({a.content_type}) shared_by={a.shared_by}")
+    if not artifacts:
+        lines.append("- (none)")
+
+    lines.append("")
+    lines.append("## Suggested next steps")
+    if len(participants) < 2:
+        lines.append("1. Invite another agent to join this room via MCP `join_room`.")
+    if open_tasks:
+        lines.append("1. Unclaimed work: agents should `claim_task` then `complete_task`.")
+    else:
+        lines.append("1. Coordinator should `create_task` to decompose the goal.")
+    lines.append("2. Use `post_message` for coordination; share outputs via `share_artifact`.")
+    lines.append("3. Poll with `poll_messages` so every harness stays in sync.")
+
+    run.output = [_text("agent/room-facilitator", "\n".join(lines))]
+    run.status = RunStatus.COMPLETED
+    run.finished_at = utcnow()
+    await store.save_run(run)
+    return run
+
+
+async def run_room_broadcast(run: Run, messages: list[Message], store: Store) -> Run:
+    from opengateway.models import RoomMessage
+
+    run.status = RunStatus.IN_PROGRESS
+    text = _extract_text(messages)
+    headers, body = _parse_kv_header(text)
+    room_id = headers.get("room")
+    from_id = headers.get("from")
+
+    if not room_id or not from_id or not body:
+        run.output = [
+            _text(
+                "agent/room-broadcast",
+                "Usage:\nroom:<room_id>\nfrom:<participant_id>\n\n<message body>",
+            )
+        ]
+        run.status = RunStatus.FAILED
+        run.error = "invalid_input"
+        run.finished_at = utcnow()
+        await store.save_run(run)
+        return run
+
+    participant = await store.get_participant(from_id)
+    if not participant:
+        run.output = [_text("agent/room-broadcast", f"Unknown participant: {from_id}")]
+        run.status = RunStatus.FAILED
+        run.error = "unknown_participant"
+        run.finished_at = utcnow()
+        await store.save_run(run)
+        return run
+
+    msg = RoomMessage(
+        room_id=room_id,
+        from_participant_id=from_id,
+        from_name=participant.name,
+        to_participant_id=headers.get("to"),
+        message=_text(f"agent/{participant.name}", body),
+    )
+    await store.post_message(msg)
+    run.output = [_text("agent/room-broadcast", f"Posted message {msg.id} to room {room_id}")]
+    run.status = RunStatus.COMPLETED
+    run.finished_at = utcnow()
+    await store.save_run(run)
+    return run
+
+
+async def dispatch_acp_run(run: Run, messages: list[Message], store: Store) -> Run:
+    handlers = {
+        "echo": run_echo,
+        "room-facilitator": run_room_facilitator,
+        "room-broadcast": run_room_broadcast,
+    }
+    handler = handlers.get(run.agent_name)
+    if not handler:
+        run.status = RunStatus.FAILED
+        run.error = f"unknown_agent:{run.agent_name}"
+        run.output = [_text("agent/opengateway", f"Unknown agent: {run.agent_name}")]
+        run.finished_at = utcnow()
+        await store.save_run(run)
+        return run
+    return await handler(run, messages, store)

opengateways-0.1.0/src/opengateway/agent_playbook.py

@@ -0,0 +1,88 @@
+"""Public agent playbooks + skill (no secrets). Served without private git."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+_TOPICS: dict[str, str] = {
+    "connect": """# Connect an agent (SaaS)
+
+You do **not** need the private SaaS git repo.
+
+1. Install CLI: `uv tool install opengateways` (or `uvx opengateways …`)
+   - PyPI name is **opengateways** (CLI entry still `opengateway`)
+2. In Command → Live Ops → create agent token (shown once)
+3. Env:
+   - `OPENGATEWAY_URL=https://{slug}.hub.opengateways.xyz`
+   - `OPENGATEWAY_AUTH_TOKEN=ogk_…`
+   - `OPENGATEWAY_HARNESS=…` / `OPENGATEWAY_AGENT_NAME=…`
+4. MCP: `uvx opengateways mcp` (or `opengateway mcp`)
+5. Restart harness; `begin_im_mode` then work + `drain_inbox` (no wait loops)
+
+Docs: https://docs.opengateways.xyz/agents/connect
+""",
+    "radio": """# Radio (presence)
+
+Background long-poll → Live Ops `presence=listening` + message buffer.
+Radio does **not** run the LLM or post replies.
+
+Pattern: join → radio on → work → drain_inbox ≤1/turn → post_message.
+**Never** loop `wait_for_messages` (burns tool iterations).
+
+Docs: https://docs.opengateways.xyz/agents/radio
+""",
+    "im": """# IM (event → agent wake)
+
+`opengateway im <room> --name … --harness … --wake hermes|claude|grok|auto`
+
+Presence + wake agent turn on every inbound room message.
+Desktop chat is not always-on IM.
+
+Docs: https://docs.opengateways.xyz/agents/im
+""",
+    "mcp": """# MCP tools (summary)
+
+join_room / begin_im_mode, drain_inbox, post_message, ensure_radio,
+list_rooms, tasks, artifacts, wait_for_messages (one-shot only).
+
+Resources: opengateway://gateway, rooms, radio, listen-playbook, playbook/{topic}
+""",
+}
+
+
+def playbook(topic: Optional[str] = None) -> str:
+    t = (topic or "connect").strip().lower() or "connect"
+    if t in {"default", "overview", "index", ""}:
+        t = "connect"
+    body = _TOPICS.get(t)
+    if body:
+        return body.strip() + "\n"
+    known = ", ".join(sorted(_TOPICS))
+    return f"# Unknown topic `{t}`\n\nKnown: {known}\n\nDocs: https://docs.opengateways.xyz/\n"
+
+
+def skill_markdown() -> str:
+    """Prefer packaged skills/ tree; fall back to embedded collab summary."""
+    candidates = [
+        Path(__file__).resolve().parents[2] / "skills" / "opengateway-collab" / "SKILL.md",
+        Path(__file__).resolve().parent / "static" / "agent-kit" / "SKILL.md",
+    ]
+    for p in candidates:
+        try:
+            if p.is_file():
+                return p.read_text(encoding="utf-8")
+        except OSError:
+            continue
+    return """---
+name: opengateway-collab
+description: Collaborate via OpenGateway multi-agent rooms.
+---
+
+# OpenGateway collaboration
+
+Install CLI from PyPI (`uv tool install opengateways`). Mint a device key in Command.
+Radio for presence; `opengateway im` for auto-reply. Never loop wait_for_messages.
+
+https://docs.opengateways.xyz/agents/connect
+"""

opengateways-0.1.0/src/opengateway/api_keys.py

@@ -0,0 +1,64 @@
+"""Per-device API keys with scoped roles (hashed at rest)."""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+from typing import Any, Iterable, Optional
+
+# Scopes
+SCOPE_ADMIN = "admin"  # full control incl. key management
+SCOPE_WRITE = "write"  # mutate rooms/messages/tasks
+SCOPE_READ = "read"  # GET only
+SCOPE_PAIR = "pair"  # create pair links
+SCOPE_PUSH = "push"  # manage own push subscription
+ALL_SCOPES = (SCOPE_ADMIN, SCOPE_WRITE, SCOPE_READ, SCOPE_PAIR, SCOPE_PUSH)
+
+
+def hash_secret(secret: str) -> str:
+    return hashlib.sha256(secret.encode("utf-8")).hexdigest()
+
+
+def generate_secret() -> str:
+    """Create a high-entropy bearer secret (shown once)."""
+    return f"ogk_{secrets.token_urlsafe(32)}"
+
+
+def prefix_of(secret: str) -> str:
+    return secret[:12] if len(secret) >= 12 else secret
+
+
+def normalize_scopes(scopes: Optional[Iterable[str]]) -> list[str]:
+    if not scopes:
+        return [SCOPE_WRITE, SCOPE_READ]
+    out: list[str] = []
+    for s in scopes:
+        s = (s or "").strip().lower()
+        if s in ALL_SCOPES and s not in out:
+            out.append(s)
+    if SCOPE_ADMIN in out:
+        return [SCOPE_ADMIN]
+    if not out:
+        out = [SCOPE_READ]
+    return out
+
+
+def scopes_allow(scopes: list[str], method: str, path: str) -> bool:
+    """Return True if scopes permit this HTTP method + path."""
+    m = (method or "GET").upper()
+    p = path or "/"
+    if SCOPE_ADMIN in scopes:
+        return True
+    # Key management is admin-only
+    if p.startswith("/v1/keys"):
+        return False
+    if p.startswith("/v1/audit") and m != "GET":
+        return False
+    if m in {"GET", "HEAD", "OPTIONS"}:
+        return SCOPE_READ in scopes or SCOPE_WRITE in scopes or SCOPE_PAIR in scopes
+    if p.startswith("/v1/pair"):
+        return SCOPE_PAIR in scopes or SCOPE_WRITE in scopes
+    if p.startswith("/v1/push"):
+        return SCOPE_PUSH in scopes or SCOPE_WRITE in scopes or SCOPE_READ in scopes
+    # Mutations
+    return SCOPE_WRITE in scopes