beadhub 0.1.0__py3-none-any.whl

beadhub/cli.py

@@ -0,0 +1,330 @@
+import json
+import os
+
+import httpx
+import typer
+import uvicorn
+
+from .config import get_settings
+from .workspace_config import get_workspace_id
+
+app = typer.Typer(help="BeadHub OSS Core CLI")
+
+
+def _resolve_workspace_id(override: str | None) -> str:
+    """Resolve workspace_id from override or .beadhub file.
+
+    Args:
+        override: Explicit workspace_id from --workspace-id flag.
+
+    Returns:
+        workspace_id string.
+
+    Raises:
+        typer.Exit: If no workspace_id is available.
+    """
+    workspace_id = get_workspace_id(override=override)
+    if not workspace_id:
+        typer.echo(
+            "Error: No workspace_id available.\n"
+            "Either:\n"
+            "  - Run 'bdh :init' to create a .beadhub file\n"
+            "  - Pass --workspace-id explicitly",
+            err=True,
+        )
+        raise typer.Exit(1)
+    return workspace_id
+
+
+def _resolve_api_key(override: str | None) -> str | None:
+    if override:
+        return override
+    return os.getenv("BEADHUB_API_KEY")
+
+
+def _handle_api_call(
+    method: str,
+    url: str,
+    allow_statuses: set[int] | None = None,
+    api_key: str | None = None,
+    **kwargs,
+) -> httpx.Response:
+    """
+    Execute an HTTP request with proper error handling.
+    Handles network errors, timeouts, and HTTP status errors gracefully.
+
+    Args:
+        method: HTTP method (GET, POST, DELETE)
+        url: Request URL
+        allow_statuses: Set of status codes to allow through (e.g., {404, 409})
+        api_key: API key to include as Authorization: Bearer header
+        **kwargs: Additional arguments passed to httpx
+    """
+    # Build headers with Authorization if provided (or from BEADHUB_API_KEY env var).
+    headers = kwargs.pop("headers", {})
+    api_key = api_key or os.getenv("BEADHUB_API_KEY")
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+
+    try:
+        if method == "GET":
+            resp = httpx.get(url, timeout=30, headers=headers, **kwargs)
+        elif method == "POST":
+            resp = httpx.post(url, timeout=30, headers=headers, **kwargs)
+        elif method == "DELETE":
+            resp = httpx.delete(url, timeout=30, headers=headers, **kwargs)
+        else:
+            raise ValueError(f"Unsupported method: {method}")
+
+        # Allow specific status codes through for caller handling
+        if allow_statuses and resp.status_code in allow_statuses:
+            return resp
+
+        # Handle common HTTP errors with friendly messages
+        if resp.status_code == 401:
+            typer.echo("Error: Unauthorized - API key required", err=True)
+            raise typer.Exit(1)
+        elif resp.status_code == 403:
+            typer.echo("Error: Forbidden - insufficient permissions", err=True)
+            raise typer.Exit(1)
+        elif resp.status_code >= 500:
+            typer.echo(f"Error: Server error ({resp.status_code})", err=True)
+            raise typer.Exit(1)
+
+        return resp
+
+    except httpx.ConnectError:
+        api_base = _get_api_base()
+        typer.echo(f"Error: Cannot connect to BeadHub API at {api_base}", err=True)
+        typer.echo("Is the server running? Try: beadhub serve", err=True)
+        raise typer.Exit(1)
+    except httpx.TimeoutException:
+        typer.echo("Error: Request timed out", err=True)
+        raise typer.Exit(1)
+    except httpx.RequestError as e:
+        typer.echo(f"Error: Network error - {e}", err=True)
+        raise typer.Exit(1)
+
+
+escalations_app = typer.Typer(help="Manage escalations")
+beads_app = typer.Typer(help="Beads integration")
+app.add_typer(escalations_app, name="escalations")
+app.add_typer(beads_app, name="beads")
+
+
+@app.command()
+def serve(
+    host: str | None = typer.Option(None, help="Host interface to bind"),
+    port: int | None = typer.Option(None, help="Port to bind"),
+    reload: bool | None = typer.Option(None, help="Enable auto-reload (development only)"),
+    log_level: str | None = typer.Option(None, help="Log level for the server"),
+) -> None:
+    """
+    Start the BeadHub API server.
+    """
+    settings = get_settings()
+
+    uvicorn.run(
+        "beadhub.api:create_app",
+        host=host or settings.host,
+        port=port or settings.port,
+        reload=reload if reload is not None else settings.reload,
+        log_level=log_level or settings.log_level,
+        factory=True,
+    )
+
+
+@app.command()
+def status(
+    workspace_id: str | None = typer.Option(
+        None, "--workspace-id", help="Workspace ID (reads from .beadhub if not provided)"
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """
+    Show BeadHub workspace status (agent presence and escalations).
+    """
+    resolved_workspace_id = _resolve_workspace_id(workspace_id)
+    params = {"workspace_id": resolved_workspace_id}
+    resp = _handle_api_call("GET", f"{_get_api_base()}/v1/status", params=params)
+    data = resp.json()
+
+    if json_output:
+        typer.echo(json.dumps(data, indent=2))
+        return
+
+    workspace = data.get("workspace", {})
+    typer.echo(f"Workspace: {workspace.get('workspace_id')}")
+    typer.echo(f"Timestamp: {data.get('timestamp')}")
+    typer.echo("")
+
+    agents = data.get("agents", [])
+    if agents:
+        typer.echo("Agents:")
+        for agent in agents:
+            typer.echo(
+                f"  {agent.get('alias', '?'):15} status={agent.get('status','?'):8} "
+                f"issue={agent.get('current_issue') or '-'}"
+            )
+    else:
+        typer.echo("Agents: (none)")
+
+    typer.echo("")
+    typer.echo(f"Escalations pending: {data.get('escalations_pending', 0)}")
+
+
+def _get_api_base() -> str:
+    return os.getenv("BEADHUB_API_URL", "http://localhost:8000")
+
+
+@escalations_app.command("list")
+def escalations_list(
+    workspace_id: str | None = typer.Option(
+        None, "--workspace-id", help="Workspace ID (reads from .beadhub if not provided)"
+    ),
+    status: str | None = typer.Option(None, help="Filter by status"),
+    agent: str | None = typer.Option(None, help="Filter by agent name"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """
+    List escalations from the API.
+    """
+    resolved_workspace_id = _resolve_workspace_id(workspace_id)
+    params: dict[str, str] = {"workspace_id": resolved_workspace_id}
+    if status:
+        params["status"] = status
+    if agent:
+        params["alias"] = agent
+
+    resp = _handle_api_call("GET", f"{_get_api_base()}/v1/escalations", params=params)
+    data = resp.json()
+
+    if json_output:
+        typer.echo(json.dumps(data, indent=2))
+        return
+
+    for esc in data.get("escalations", []):
+        typer.echo(
+            f"{esc['escalation_id']}  {esc['status']:9}  " f"{esc['alias']:15}  {esc['subject']}"
+        )
+
+
+@escalations_app.command("view")
+def escalations_view(escalation_id: str) -> None:
+    """
+    View escalation details.
+    """
+    resp = _handle_api_call(
+        "GET", f"{_get_api_base()}/v1/escalations/{escalation_id}", allow_statuses={404}
+    )
+    if resp.status_code == 404:
+        typer.echo("Error: Escalation not found", err=True)
+        raise typer.Exit(1)
+    typer.echo(json.dumps(resp.json(), indent=2))
+
+
+@beads_app.command("issues")
+def beads_issues(
+    workspace_id: str | None = typer.Option(
+        None, "--workspace-id", help="Workspace ID (reads from .beadhub if not provided)"
+    ),
+    api_key: str | None = typer.Option(
+        None, "--api-key", help="BeadHub API key (defaults to BEADHUB_API_KEY)"
+    ),
+    status: str | None = typer.Option(None, help="Filter by status"),
+    assignee: str | None = typer.Option(None, help="Filter by assignee"),
+    label: str | None = typer.Option(None, help="Filter by label"),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """
+    List Beads issues from BeadHub.
+    """
+    resolved_workspace_id = _resolve_workspace_id(workspace_id)
+    resolved_api_key = _resolve_api_key(api_key)
+    if not resolved_api_key:
+        typer.echo("Error: BEADHUB_API_KEY not set (run `bdh :init` or pass --api-key)", err=True)
+        raise typer.Exit(1)
+    params: dict[str, str] = {"workspace_id": resolved_workspace_id}
+    if status:
+        params["status"] = status
+    if assignee:
+        params["assignee"] = assignee
+    if label:
+        params["label"] = label
+
+    resp = _handle_api_call(
+        "GET",
+        f"{_get_api_base()}/v1/beads/issues",
+        params=params,
+        api_key=resolved_api_key,
+    )
+    data = resp.json()
+
+    if json_output:
+        typer.echo(json.dumps(data, indent=2))
+        return
+
+    for issue in data.get("issues", []):
+        typer.echo(
+            f"{issue['bead_id']}  P{issue['priority']}  " f"{issue['status']:10}  {issue['title']}"
+        )
+
+
+@beads_app.command("ready")
+def beads_ready(
+    workspace_id: str | None = typer.Option(
+        None, "--workspace-id", help="Workspace ID (reads from .beadhub if not provided)"
+    ),
+    api_key: str | None = typer.Option(
+        None, "--api-key", help="BeadHub API key (defaults to BEADHUB_API_KEY)"
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON"),
+) -> None:
+    """
+    Show Beads issues that are ready to work on.
+    """
+    resolved_workspace_id = _resolve_workspace_id(workspace_id)
+    resolved_api_key = _resolve_api_key(api_key)
+    if not resolved_api_key:
+        typer.echo("Error: BEADHUB_API_KEY not set (run `bdh :init` or pass --api-key)", err=True)
+        raise typer.Exit(1)
+    params = {"workspace_id": resolved_workspace_id}
+    resp = _handle_api_call(
+        "GET",
+        f"{_get_api_base()}/v1/beads/ready",
+        params=params,
+        api_key=resolved_api_key,
+    )
+    data = resp.json()
+
+    if json_output:
+        typer.echo(json.dumps(data, indent=2))
+        return
+
+    for issue in data.get("issues", []):
+        typer.echo(f"{issue['bead_id']}  P{issue['priority']}  {issue['title']}")
+
+
+@escalations_app.command("respond")
+def escalations_respond(
+    escalation_id: str,
+    choice: str = typer.Option(..., "--choice", help="Chosen response"),
+    note: str | None = typer.Option(None, "--note", help="Optional note"),
+) -> None:
+    """
+    Respond to an escalation.
+    """
+    payload = {"response": choice}
+    if note:
+        payload["note"] = note
+
+    resp = _handle_api_call(
+        "POST",
+        f"{_get_api_base()}/v1/escalations/{escalation_id}/respond",
+        allow_statuses={404},
+        json=payload,
+    )
+    if resp.status_code == 404:
+        typer.echo("Error: Escalation not found", err=True)
+        raise typer.Exit(1)
+    typer.echo(json.dumps(resp.json(), indent=2))

beadhub/config.py

@@ -0,0 +1,65 @@
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class Settings:
+    host: str
+    port: int
+    log_level: str
+    reload: bool
+    redis_url: str
+    database_url: str
+    presence_ttl_seconds: int
+    dashboard_human: str
+
+
+def get_settings() -> Settings:
+    """
+    Load settings from environment at call time.
+
+    Accepts both prefixed (BEADHUB_*) and unprefixed env vars for flexibility.
+    """
+    database_url = os.getenv("BEADHUB_DATABASE_URL") or os.getenv("DATABASE_URL")
+    if not database_url:
+        raise ValueError(
+            "DATABASE_URL or BEADHUB_DATABASE_URL environment variable is required. "
+            "Example: postgresql://user:pass@localhost:5432/beadhub"
+        )
+
+    redis_url = (
+        os.getenv("BEADHUB_REDIS_URL") or os.getenv("REDIS_URL") or "redis://localhost:6379/0"
+    )
+
+    port_str = os.getenv("BEADHUB_PORT", "8000")
+    try:
+        port = int(port_str)
+        if not 1 <= port <= 65535:
+            raise ValueError(f"BEADHUB_PORT must be between 1 and 65535, got {port}")
+    except ValueError as e:
+        if "invalid literal" in str(e):
+            raise ValueError(f"BEADHUB_PORT must be a valid integer, got '{port_str}'")
+        raise
+
+    presence_ttl_str = os.getenv("BEADHUB_PRESENCE_TTL_SECONDS", "1800")
+    try:
+        presence_ttl = int(presence_ttl_str)
+        if presence_ttl < 10:
+            raise ValueError("BEADHUB_PRESENCE_TTL_SECONDS must be at least 10")
+    except ValueError as e:
+        if "invalid literal" in str(e):
+            raise ValueError(
+                f"BEADHUB_PRESENCE_TTL_SECONDS must be a valid integer, got '{presence_ttl_str}'"
+            )
+        raise
+
+    return Settings(
+        host=os.getenv("BEADHUB_HOST", "0.0.0.0"),
+        port=port,
+        log_level=os.getenv("BEADHUB_LOG_LEVEL", "info"),
+        reload=os.getenv("BEADHUB_RELOAD", "false").lower() == "true",
+        redis_url=redis_url,
+        database_url=database_url,
+        presence_ttl_seconds=presence_ttl,
+        dashboard_human=os.getenv("BEADHUB_DASHBOARD_HUMAN", "admin"),
+    )

beadhub/db.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from fastapi import Request
+from pgdbm import AsyncDatabaseManager, DatabaseConfig
+from pgdbm.migrations import AsyncMigrationManager
+
+from .config import get_settings
+
+
+class DatabaseInfra:
+    """
+    Shared pgdbm infrastructure for BeadHub.
+
+    Creates a single shared pool and schema-specific managers
+    for core modules (server, beads).
+    """
+
+    def __init__(self) -> None:
+        self._shared_pool: Optional[Any] = None
+        self._managers: Dict[str, AsyncDatabaseManager] = {}
+        self._initialized: bool = False
+        self._init_lock: asyncio.Lock = asyncio.Lock()
+        self._owns_pool: bool = True
+
+    async def initialize(self, *, shared_pool: Optional[Any] = None) -> None:
+        if self._initialized:
+            return
+
+        async with self._init_lock:
+            # Double-check after acquiring lock (another coroutine may have initialized)
+            if self._initialized:
+                return  # type: ignore[unreachable]  # Valid double-checked locking
+
+            if shared_pool is None:
+                settings = get_settings()
+                config = DatabaseConfig(connection_string=settings.database_url)
+                shared_pool = await AsyncDatabaseManager.create_shared_pool(config)
+                self._owns_pool = True
+            else:
+                # Host application owns lifecycle of the pool.
+                self._owns_pool = False
+
+            self._shared_pool = shared_pool
+
+            self._managers["server"] = AsyncDatabaseManager(
+                pool=shared_pool,
+                schema="server",
+            )
+            self._managers["beads"] = AsyncDatabaseManager(
+                pool=shared_pool,
+                schema="beads",
+            )
+            # BeadHub implements the aweb protocol; keep identity/coordination tables
+            # in a dedicated schema for clean extraction.
+            self._managers["aweb"] = AsyncDatabaseManager(
+                pool=shared_pool,
+                schema="aweb",
+            )
+
+            base_dir = Path(__file__).resolve().parent
+            migrations_root = base_dir / "migrations"
+
+            for name, db in self._managers.items():
+                # Ensure schema exists before applying migrations
+                await db.execute(f'CREATE SCHEMA IF NOT EXISTS "{db.schema}"')
+
+                if name == "aweb":
+                    # Apply aweb protocol migrations using the same module_name as the
+                    # standalone aweb server so migration history is shared.
+                    import aweb as aweb_pkg
+
+                    aweb_root = Path(aweb_pkg.__file__).resolve().parent
+                    module_migrations = aweb_root / "migrations" / "aweb"
+                    module_name = "aweb-aweb"
+                else:
+                    module_migrations = migrations_root / name
+                    module_name = f"beadhub-{name}"
+
+                if module_migrations.is_dir():
+                    manager = AsyncMigrationManager(
+                        db,
+                        migrations_path=str(module_migrations),
+                        module_name=module_name,
+                    )
+                    await manager.apply_pending_migrations()
+
+            self._initialized = True
+
+    async def close(self) -> None:
+        if self._shared_pool is not None and self._owns_pool:
+            await self._shared_pool.close()
+
+        self._managers.clear()
+        self._shared_pool = None
+        self._initialized = False
+        self._owns_pool = True
+
+    @property
+    def is_initialized(self) -> bool:
+        """Check if the database infrastructure is initialized."""
+        return self._initialized
+
+    def get_manager(self, name: str = "server") -> AsyncDatabaseManager:
+        if not self._initialized:
+            raise RuntimeError(
+                "DatabaseInfra is not initialized. " "Call 'await db_infra.initialize()' first."
+            )
+        manager = self._managers.get(name)
+        if manager is None:
+            available = ", ".join(sorted(self._managers.keys())) or "(none)"
+            raise RuntimeError(
+                f"Unknown database manager '{name}'. Available managers: {available}"
+            )
+        return manager
+
+
+db_infra = DatabaseInfra()
+
+
+def get_db_infra(request: Request) -> DatabaseInfra:
+    """FastAPI dependency that returns the DatabaseInfra from app state.
+
+    Works in both standalone and library modes since both set app.state.db.
+    """
+    return request.app.state.db

beadhub/defaults/invariants/01-tracking-bdh-only.md

@@ -0,0 +1,11 @@
+---
+id: tracking.bdh-only
+title: Use bdh for tracking
+---
+
+Track all tasks and issues with `bdh`. Do not create markdown TODO lists or external trackers.
+
+- Run `bdh :policy` for full command reference and workflow details
+- Use `bdh ready` to find unblocked work
+- Link discovered work with `--deps discovered-from:<parent-id>`
+- Store planning docs in `history/` if needed

beadhub/defaults/invariants/02-communication-mail-first.md

@@ -0,0 +1,36 @@
+---
+id: communication.mail-first
+title: Mail-first communication
+---
+
+Default to mail (`bdh :aweb mail`) for coordination.
+
+Use mail for:
+- Status updates and progress reports
+- Review requests and feedback
+- FYI notifications
+- Non-blocking questions
+
+## Sending Messages
+
+```bash
+bdh :aweb mail send <agent> "Status update: completed bd-42"
+bdh :aweb mail send <agent> "Review request: PR #123 ready" --subject "Review needed"
+```
+
+## Checking Your Inbox
+
+```bash
+bdh :aweb mail list           # Show unread messages
+bdh :aweb mail list --all     # Include read messages
+```
+
+## Reading Messages
+
+```bash
+bdh :aweb mail open <sender>   # Read unread mail from sender (acknowledges)
+```
+
+Use chat (`bdh :aweb chat`) only when you need a synchronous answer to proceed. See the **communication.chat** invariant for chat details.
+
+**Respond immediately to WAITING notifications** — someone is blocked waiting for your reply.

beadhub/defaults/invariants/03-communication-chat.md

@@ -0,0 +1,60 @@
+---
+id: communication.chat
+title: Chat for synchronous coordination
+---
+
+Use chat (`bdh :aweb chat`) when you need a **synchronous answer** to proceed. Sessions are persistent and messages are never lost.
+
+## Subcommands
+
+| Subcommand | Purpose |
+|------------|---------|
+| `chat send <alias> "msg"` | Send a message (60s default wait) |
+| `chat send <alias> "msg" --start-conversation` | Start a new exchange (5 min default wait) |
+| `chat send <alias> "msg" --leave-conversation` | Send final message and exit |
+| `chat open <alias>` | Read unread messages (marks as read) |
+| `chat pending` | List chat sessions with unread messages |
+| `chat history <alias>` | Show conversation history |
+| `chat hang-on <alias> "msg"` | Request more time before replying |
+
+## Starting vs Continuing Conversations
+
+**Starting a new exchange** — initiates and waits for the target to notice:
+```bash
+bdh :aweb chat send <agent> "Can we discuss the API design?" --start-conversation
+```
+
+**Continuing a conversation** — reply and wait briefly:
+```bash
+bdh :aweb chat send <agent> "What about the error handling?"
+```
+
+**Signing off** — send final message, exit immediately:
+```bash
+bdh :aweb chat send <agent> "Got it, thanks!" --leave-conversation
+```
+
+## Wait Behavior
+
+`--start-conversation` waits 5 minutes by default; a plain `send` waits 60 seconds. Override with `--wait N` (seconds).
+
+## Receiving Messages
+
+Check for pending conversations:
+```bash
+bdh :aweb chat pending
+```
+
+Notifications appear on any bdh command:
+```
+WAITING: agent-p1 is waiting for you
+   "Is project_id nullable?"
+   → Reply: bdh :aweb chat send agent-p1 "your reply"
+```
+
+**WAITING** means the sender is actively waiting — reply promptly.
+
+If you need more time before replying:
+```bash
+bdh :aweb chat hang-on agent-p1 "Looking into it, give me a few minutes"
+```

beadhub/defaults/invariants/04-identity-no-impersonation.md

@@ -0,0 +1,17 @@
+---
+id: identity.no-impersonation
+title: No workspace impersonation
+---
+
+Never run `bdh` from another workspace or worktree.
+
+`bdh` derives your identity from the `.beadhub` file in the current worktree. Running `bdh` from another repo or worktree can impersonate that workspace's agent, causing:
+
+- Messages sent as the wrong agent
+- Work claimed under the wrong identity
+- Confusion in coordination
+
+**Always verify** you're in the correct worktree before running bdh commands:
+```bash
+bdh :aweb whoami    # Check your identity
+```

beadhub/defaults/invariants/05-collaborate.md

@@ -0,0 +1,12 @@
+---
+id: teamwork.collaborate
+title: Collaborate toward the goal
+---
+
+You are part of a team working toward a shared goal. Optimize for the project outcome, not your individual activity.
+
+- Help teammates when they're blocked — respond promptly to messages
+- Pick up work that advances the goal, even if it's not "yours"
+- Escalate blockers early rather than spinning alone
+- Keep changes small and reviewable so others can build on your work
+