beadhub 0.1.0__py3-none-any.whl

beadhub/workspace_config.py

@@ -0,0 +1,202 @@
+"""Workspace configuration reading from .beadhub files."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+MAX_CONFIG_SIZE = 4096  # 4KB max for .beadhub file
+
+
+@dataclass
+class WorkspaceConfig:
+    """Configuration loaded from a .beadhub file."""
+
+    workspace_id: str | None = None
+    beadhub_url: str | None = None
+    alias: str | None = None
+    human_name: str | None = None
+    project_slug: str | None = None
+    repo_origin: str | None = None
+
+
+def _strip_quotes(value: str) -> str:
+    """Strip matching quotes from a value string.
+
+    Only removes quotes if they match (both single or both double).
+    """
+    value = value.strip()
+    if len(value) >= 2:
+        if (value.startswith('"') and value.endswith('"')) or (
+            value.startswith("'") and value.endswith("'")
+        ):
+            return value[1:-1]
+    return value
+
+
+def _parse_beadhub_file(content: str) -> dict[str, str]:
+    """Parse simple YAML-like .beadhub config file.
+
+    Format:
+        # comments are ignored
+        key: "value"   # quoted values
+        key: value     # unquoted values
+
+    Note: This is NOT a full YAML parser. It only supports simple key: value lines.
+    """
+    config: dict[str, str] = {}
+    for line in content.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if ":" in line:
+            key, value = line.split(":", 1)
+            key = key.strip()
+            if not key:
+                continue
+            value = _strip_quotes(value)
+            if value:
+                config[key] = value
+    return config
+
+
+def load_workspace_config(path: Path | None = None) -> WorkspaceConfig | None:
+    """Load workspace configuration from .beadhub file.
+
+    Args:
+        path: Directory containing .beadhub file. Defaults to current directory.
+              Security note: Caller must ensure this path is trusted.
+
+    Returns:
+        WorkspaceConfig if file exists, None if file doesn't exist.
+
+    Raises:
+        ValueError: If file is too large or unreadable.
+    """
+    if path is None:
+        path = Path.cwd()
+
+    config_file = path / ".beadhub"
+    if not config_file.exists():
+        return None
+
+    try:
+        file_size = config_file.stat().st_size
+        if file_size > MAX_CONFIG_SIZE:
+            raise ValueError(f".beadhub file too large ({file_size} bytes, max {MAX_CONFIG_SIZE})")
+        content = config_file.read_text(encoding="utf-8")
+    except PermissionError:
+        raise ValueError(f"Cannot read {config_file}: Permission denied")
+    except UnicodeDecodeError:
+        raise ValueError(f"{config_file} is not valid UTF-8 text")
+    except OSError as e:
+        raise ValueError(f"Error reading {config_file}: {e}")
+
+    parsed = _parse_beadhub_file(content)
+
+    return WorkspaceConfig(
+        workspace_id=parsed.get("workspace_id"),
+        beadhub_url=parsed.get("beadhub_url"),
+        alias=parsed.get("alias"),
+        human_name=parsed.get("human_name"),
+        project_slug=parsed.get("project_slug"),
+        repo_origin=parsed.get("repo_origin"),
+    )
+
+
+def get_workspace_id(override: str | None = None, path: Path | None = None) -> str | None:
+    """Get workspace_id, preferring explicit override over file.
+
+    Args:
+        override: Explicit workspace_id (takes precedence).
+        path: Directory containing .beadhub file.
+
+    Returns:
+        workspace_id or None if not available.
+    """
+    if override:
+        return override
+
+    config = load_workspace_config(path)
+    if config:
+        return config.workspace_id
+
+    return None
+
+
+def get_project_slug(override: str | None = None, path: Path | None = None) -> str | None:
+    """Get project_slug, preferring explicit override over file.
+
+    Args:
+        override: Explicit project_slug (takes precedence).
+        path: Directory containing .beadhub file.
+
+    Returns:
+        project_slug or None if not available.
+    """
+    if override:
+        return override
+
+    config = load_workspace_config(path)
+    if config:
+        return config.project_slug
+
+    return None
+
+
+def get_human_name(override: str | None = None, path: Path | None = None) -> str | None:
+    """Get human_name, preferring explicit override over file.
+
+    Args:
+        override: Explicit human_name (takes precedence).
+        path: Directory containing .beadhub file.
+
+    Returns:
+        human_name or None if not available.
+    """
+    if override:
+        return override
+
+    config = load_workspace_config(path)
+    if config:
+        return config.human_name
+
+    return None
+
+
+def get_alias(override: str | None = None, path: Path | None = None) -> str | None:
+    """Get alias, preferring explicit override over file.
+
+    Args:
+        override: Explicit alias (takes precedence).
+        path: Directory containing .beadhub file.
+
+    Returns:
+        alias or None if not available.
+    """
+    if override:
+        return override
+
+    config = load_workspace_config(path)
+    if config:
+        return config.alias
+
+    return None
+
+
+def get_repo_origin(override: str | None = None, path: Path | None = None) -> str | None:
+    """Get repo_origin, preferring explicit override over file.
+
+    Args:
+        override: Explicit repo_origin (takes precedence).
+        path: Directory containing .beadhub file.
+
+    Returns:
+        repo_origin or None if not available.
+    """
+    if override:
+        return override
+
+    config = load_workspace_config(path)
+    if config:
+        return config.repo_origin
+
+    return None

beadhub-0.1.0.dist-info/METADATA

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: beadhub
+Version: 0.1.0
+Summary: Real-time coordination layer for AI agent teams. File locking, messaging, escalations, and Beads integration.
+Project-URL: Homepage, https://github.com/beadhub/beadhub
+Project-URL: Documentation, https://github.com/beadhub/beadhub#readme
+Project-URL: Repository, https://github.com/beadhub/beadhub.git
+Project-URL: Issues, https://github.com/beadhub/beadhub/issues
+Author-email: Juan Reyero <juan@juanreyero.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,beads,coordination,file-locking,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: aiofiles>=25.1.0
+Requires-Dist: aweb>=0.1.0
+Requires-Dist: bcrypt>=5.0.0
+Requires-Dist: email-validator>=2.3.0
+Requires-Dist: fastapi>=0.93.0
+Requires-Dist: httpx>=0.23.0
+Requires-Dist: pgdbm>=0.4.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: redis>=4.2.0
+Requires-Dist: typer>=0.6.0
+Requires-Dist: uvicorn>=0.20.0
+Description-Content-Type: text/markdown
+
+# BeadHub
+
+Real-time coordination for AI agent teams.
+
+## The Problem
+
+When multiple AI agents work on a shared codebase, they collide. Two agents claim the same issue. Both edit the same file. Merge conflicts pile up. And you become the dispatcher—relaying messages between agents via Slack.
+
+BeadHub lets agents coordinate themselves. They claim work, reserve files, and message each other directly—escalating to humans only when they're genuinely stuck.
+
+**BeadHub is to [Beads](https://github.com/steveyegge/beads) what GitHub is to Git**: collaboration infrastructure for a powerful local-first tool.
+
+## Quick Start
+
+Prerequisites:
+- Docker
+- [Beads](https://github.com/steveyegge/beads) (`bd` CLI) for issue tracking
+- A git repository with a remote origin configured
+
+```bash
+# Start the BeadHub server
+git clone https://github.com/beadhub/beadhub.git
+cd beadhub
+make start                              # or: POSTGRES_PASSWORD=demo docker compose up -d
+
+# Install the bdh CLI
+curl -fsSL https://raw.githubusercontent.com/beadhub/bdh/main/install.sh | bash
+
+# Initialize a workspace (must be a git repo with remote origin)
+cd /path/to/your-repo
+bdh :init --project demo
+
+# Open the dashboard (auto-authenticates using your project API key)
+bdh :dashboard
+```
+
+Dashboard:
+- Open and auto-authenticate: `bdh :dashboard`
+- If you need to paste a key manually, use the `api_key` from `~/.config/aw/config.yaml` (the account selected by `.aw/context`)
+
+## See It In Action
+
+Here's what multi-agent coordination looks like. You have three agents: a coordinator and two implementers.
+
+> **Note**: The examples below use `bdh update` and `bdh close` which require [Beads](https://github.com/steveyegge/beads) for issue tracking. Install beads first, then run `bd init` in your repo.
+
+### 1. Agents come online
+
+**coord-main** runs `bdh :aweb who` to see who's online:
+
+```
+Project: <project_id>
+
+ONLINE
+  bob-backend (agent) — active
+  alice-frontend (agent) — active
+```
+
+### 2. Coordinator assigns work via chat
+
+**coord-main** runs `bdh :aweb chat send bob "Can you handle the API endpoints?" --wait 300`:
+
+```
+Sent chat to bob (session_id=...)
+```
+
+Bob is idle. **You** tell bob to check chat.
+
+**bob-backend** runs `bdh :aweb chat pending`:
+
+```
+CHATS: 1 unread conversation(s)
+
+- coord-main (unread: 1)
+```
+
+**bob-backend** runs `bdh :aweb chat send coord-main "Got it, I'll take the API work"`:
+
+```
+coord-main: Can you handle the API endpoints?
+```
+
+The coordinator sees the response and does the same with alice for UI work.
+
+### 3. Agents claim and complete work
+
+**bob-backend** runs `bdh update bd-12 --status in_progress` to claim his issue.
+
+If bob tries to claim something alice already has:
+
+**bob-backend** runs `bdh update bd-15 --status in_progress`:
+
+```
+REJECTED: bd-15 is being worked on by alice-frontend (juan)
+
+Options:
+  - Pick different work: bdh ready
+  - Message them: bdh :aweb mail send alice-frontend "message"
+  - Escalate: bdh :escalate "subject" "situation"
+```
+
+No collision. No confusion. Agents resolve conflicts directly.
+
+## Adding More Agents
+
+Each agent needs its own worktree with its own identity:
+
+```bash
+bdh :add-worktree backend
+```
+
+Or do it manually:
+
+```bash
+git worktree add ../myproject-bob-backend -b bob-backend
+cd ../myproject-bob-backend
+bdh :init --project demo --alias bob-backend --human "$USER"
+```
+
+## Commands
+
+### Status and visibility
+
+```bash
+bdh :aweb whoami      # Your aweb identity (project/agent)
+bdh :aweb who         # Who's online?
+bdh ready            # Find available work
+bdh :aweb locks       # See active locks
+```
+
+### Issue workflow
+
+```bash
+bdh ready                              # Find available work
+bdh update bd-42 --status in_progress  # Claim an issue
+bdh close bd-42                        # Complete work
+```
+
+### Chat (synchronous)
+
+Use chat when you need an answer to proceed. The sender waits.
+
+```bash
+bdh :aweb chat send alice "Quick question..." --wait 300  # Send, wait up to 5 min
+bdh :aweb chat pending                                     # Check pending chats
+bdh :aweb chat send alice "Here's the answer"              # Reply
+```
+
+### Mail (async)
+
+Use mail for status updates, handoffs, FYIs—anything that doesn't need an immediate response.
+
+```bash
+bdh :aweb mail send alice "Login bug fixed. Changed session handling."
+bdh :aweb mail list          # Check messages
+bdh :aweb mail open alice    # Read + acknowledge from specific sender
+```
+
+### Escalation
+
+When agents can't resolve something themselves:
+
+```bash
+bdh :escalate "Need human decision" "Alice and I both need to modify auth.py..."
+```
+
+## File Reservations
+
+bdh automatically reserves files you modify—no commands needed. Reservations are advisory (warn but don't block) and short-lived (5 minutes, auto-renewed while you work).
+
+When an agent runs `bdh :aweb locks`:
+
+```
+## Other Agents' Reservations
+Do not edit these files:
+- `src/auth.py` — bob-backend (expires in 4m30s) "auto-reserve"
+- `src/api.py` — alice-frontend (expires in 3m15s) "auto-reserve"
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      BeadHub Server                         │
+│   Claims · Reservations · Presence · Messages · Beads Sync  │
+├─────────────────────────────────────────────────────────────┤
+│  PostgreSQL              Redis                              │
+│  (claims, issues)        (presence, messages)               │
+└─────────────────────────────────────────────────────────────┘
+        ▲                    ▲                    ▲
+        │                    │                    │
+   ┌────┴────┐          ┌────┴────┐          ┌────┴────┐
+   │  Agent  │          │  Agent  │          │  Human  │
+   │ Repo A  │          │ Repo B  │          │ (dash)  │
+   └─────────┘          └─────────┘          └─────────┘
+```
+
+Multiple agents across different repos coordinate through the same BeadHub server.
+
+## Requirements
+
+- Docker and Docker Compose
+- [Beads](https://github.com/steveyegge/beads) for issue tracking
+
+## Documentation
+
+- [bdh Command Reference](docs/bdh.md)
+- [Deployment Guide](docs/deployment.md)
+- [Development Guide](docs/development.md)
+- [Changelog](CHANGELOG.md)
+
+## Cleanup
+
+```bash
+docker compose down -v
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE)

beadhub-0.1.0.dist-info/RECORD

@@ -0,0 +1,54 @@
+beadhub/__init__.py,sha256=xV4F4KIcDjzjBAubgbfnqXQGykDSVbCZ3h8gBsKLJPI,257
+beadhub/api.py,sha256=SdNS8wyoTSpB2Reo7mdiwZEIMyfWllAwzBM3U_V3-yQ,9696
+beadhub/auth.py,sha256=re60LYsPzrB7WU8WB9vYoo7QNMSPbQlUI1gfxuYGL9U,3202
+beadhub/aweb_context.py,sha256=XbeJd_F1YGgJyCnqoHgBuALwSZnjeT-8CTfHjPOIFR0,1905
+beadhub/aweb_introspection.py,sha256=VuJxtGoru6llD9fEziNXnHuv_Mk8EdSrVc37K16aSBc,2562
+beadhub/beads_sync.py,sha256=bRpsJuBTozfj-Yqjjc0Au4mQtHcjTl-BiZPb7oXaDQQ,18086
+beadhub/cli.py,sha256=GsL4DK5nNSouwv4zvAqThz8o9wK3FBGGbCe9CSuKBrU,10670
+beadhub/config.py,sha256=ceuQrP_kZDmTH_bBjcYHH2y5xDqbXl_P8rjgRnB1Gzg,2077
+beadhub/db.py,sha256=an_Sgg3E8BA7ZvC5ruSXlYn1tQnDwqyffoqbQiQJIVk,4628
+beadhub/defaults.py,sha256=aeppczKQCsnFYH9hBR4gEOMQiUZEWyzajAsD-hhH4ec,7978
+beadhub/events.py,sha256=jTxkS4wOXzmiNhO-THlMN3icpI1xm60HF2mq_TQGLqY,23609
+beadhub/internal_auth.py,sha256=0gMnQZTGSKum6RG_aegPAYA9Y0Su-POD3w5hsBXPv6Q,4089
+beadhub/jsonl.py,sha256=rihr6dZtpetCmjI-NAcwC3Nwo59ze7hiW08iBjv7GtA,2164
+beadhub/logging.py,sha256=coreUgbK0imFhuh0wqXG_08ndrP9vt8oSoXr0be3-ZA,1928
+beadhub/names.py,sha256=xKgQgWbS7rvK3Eac_S9Q1y7tq4qI_CNGZbUBsRsifOk,512
+beadhub/notifications.py,sha256=wqRkXBxqIGq6eKACRlj6f14fPsTrJd-65ucxZoynZHw,8487
+beadhub/pagination.py,sha256=lcKBw_CBwBg5_wdBENtXuuL8U6Ncaxib9ajOwc_-Rcc,3893
+beadhub/presence.py,sha256=OgKgooH9ZRdmK8INsVyUiz4IRrGEQ-MLrxJdQBvdn_0,15393
+beadhub/rate_limit.py,sha256=KkicwCZv8aOwoENgFc2m1PMvLDa5CE4SBYXlmWBOsH4,4720
+beadhub/redis_client.py,sha256=f9IRPQH0DOiM5hC7D_LxFiCr7yCyqjZNayA8a-Q9l4U,273
+beadhub/roles.py,sha256=442UQxgQ9lYM_ccyvwn803s-Kt-0ZEcrDMk8-nsOHps,1086
+beadhub/workspace_config.py,sha256=d_xECpDvYZ29qpQb9E1naBhQyHuKcAzjZnguRJVC8bQ,5548
+beadhub/defaults/invariants/01-tracking-bdh-only.md,sha256=_ipwZg5sENZTBfPA-JUuxRniWA8nW5c9aoB09KeIiWA,375
+beadhub/defaults/invariants/02-communication-mail-first.md,sha256=OIpgBFKAndqdL6Z37UAO_Jxfke9YcpDD9GPtswi3qsY,925
+beadhub/defaults/invariants/03-communication-chat.md,sha256=D5_mLxTP-1B1BRWoZd-TQUkpmLbwotQ8tg4J2IoFiws,1844
+beadhub/defaults/invariants/04-identity-no-impersonation.md,sha256=mlwztSun5hNxqD3ADcrXUBYHtcs86fFMnZAlZ_THuPo,534
+beadhub/defaults/invariants/05-collaborate.md,sha256=KvOwHgB5cyn55IsySvZx5tDosaL_QTVUbwNcE3IQT4M,445
+beadhub/defaults/roles/backend.md,sha256=M3FBwOb9MIb6NUVNooS3aFbz20KNBMsAEM45TMCFmmo,1404
+beadhub/defaults/roles/coordinator.md,sha256=bjlMxNUNdmk0lVX0l9jwu-YbqkUzd26maiV19WHURG0,1200
+beadhub/defaults/roles/frontend.md,sha256=gXBqQg2h0oOQqzmCqYDGIdoZZBNaCduLNbfVMjSOTMY,2014
+beadhub/defaults/roles/implementer.md,sha256=s-mte97p5yEuKQctCgjOVb7ncRT1NMARlPujyYteZgk,1886
+beadhub/defaults/roles/reviewer.md,sha256=8cs3vvI6AT0dcN2Qybq7Rr7zBIBtmq4AeRzlNvKSfa4,1442
+beadhub/defaults/roles/startup-expert.md,sha256=JKygzye541J_fd2u989gBYocKNHEsvAyDZJfWRZ4EQA,4793
+beadhub/migrations/beads/001_initial.sql,sha256=I47sncZ9R7fyF42tuBAmouCtyePw3UTWy-Had0G5yVw,2275
+beadhub/migrations/beads/002_search_indexes.sql,sha256=R2ZIc-SO87nv8UyN7Q4nIZfsUUu7QYn_EiZAhYGvzWk,990
+beadhub/migrations/server/001_initial.sql,sha256=FNLSpwg0X-vlPBLEtvYEsMpKG_12OspmH7upmZhPiv0,12339
+beadhub/routes/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+beadhub/routes/agents.py,sha256=d_tu6GS-WjRnnAtok1QxGv2EtPeQysjY9aWPBbDZwDU,9667
+beadhub/routes/bdh.py,sha256=UZ41aeSA1fnOukNZhXFHYbsHRd2piHCn4Toa4-TOGMU,21274
+beadhub/routes/beads.py,sha256=NE1Dnyev9AXIXd6i42nUai4QVUIT3nx-d4JQaKRhGHY,27049
+beadhub/routes/claims.py,sha256=Ab0PWkN2zziEHvS4b9IYFSuepAFeULhRSSg-iHzRHYE,4676
+beadhub/routes/escalations.py,sha256=kTRV1-PqxnzAz0wFpuwcypXaJMixx10pL5EDY9_O5Cc,15766
+beadhub/routes/init.py,sha256=YFSCB-mGQQSoDeUB5mDB4P9hiV2N1tJ_CLcQslsG-pA,12092
+beadhub/routes/mcp.py,sha256=V46oiGUtG7iZ-Q4waRVBon7qezrYOm_jb0mM3u-ZhBs,12140
+beadhub/routes/policies.py,sha256=8RKRb53uGdGAqAmWy5WwTm67jlgkwGHjbVusUwpXY6k,24885
+beadhub/routes/repos.py,sha256=Yfa6ZRZDWAMnUitolFlCDln5Tl3q4Oh4uSPtgvMOfhk,16136
+beadhub/routes/status.py,sha256=QvA8GsDYw9ZJxNMdq-Q6AvSmmnAk6_8vktvFiOgZQq8,19908
+beadhub/routes/subscriptions.py,sha256=6EgpKseRnmMgY0STVRY02Ss5_hLUrmCcH1j9BZW__aI,11733
+beadhub/routes/workspaces.py,sha256=qRwqdfewKMrQb_e772sJklUD5MtWxtl22Lm-lmHO_8Y,58554
+beadhub-0.1.0.dist-info/METADATA,sha256=i0RxPsUCMdK1eBgmVxRzXrDQGtNFfmWr_nZwJE7V-7Y,8224
+beadhub-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+beadhub-0.1.0.dist-info/entry_points.txt,sha256=R0WP_G-w5OLtcXmJBYWegf7nz19r8fWsLmvXcKhCVzg,41
+beadhub-0.1.0.dist-info/licenses/LICENSE,sha256=xkOblX-z-aMOHH5l6MnEAVc0dFrpwFN2dPJGFvKsXtg,1068
+beadhub-0.1.0.dist-info/RECORD,,

beadhub-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

beadhub-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+beadhub = beadhub:main

beadhub-0.1.0.dist-info/licenses/LICENSE

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