okf-agentbus 0.2.3__py3-none-any.whl

agentbus/__init__.py

@@ -0,0 +1,3 @@
+"""AgentBus — local MCP event log and advisory lease locks for multi-agent workspaces."""
+
+__version__ = "0.2.3"

agentbus/auth.py

@@ -0,0 +1,81 @@
+"""Workspace-scoped ephemeral token authentication for publish."""
+
+from __future__ import annotations
+
+import os
+import secrets
+from pathlib import Path
+
+TOKEN_FILENAME = "token"
+
+
+def token_path(workspace: Path) -> Path:
+    return workspace.resolve() / ".agentbus" / TOKEN_FILENAME
+
+
+def generate_token() -> str:
+    return secrets.token_urlsafe(32)
+
+
+def read_workspace_token(workspace: Path) -> str | None:
+    path = token_path(workspace)
+    if not path.is_file():
+        return None
+    return path.read_text(encoding="utf-8").strip()
+
+
+def write_workspace_token(workspace: Path, token: str) -> Path:
+    path = token_path(workspace)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(token + "\n", encoding="utf-8")
+    os.chmod(path, 0o600)
+    return path
+
+
+def ensure_ephemeral_token(workspace: Path, *, rotate: bool = False) -> str:
+    """Create or reuse workspace token. Set rotate=True to regenerate."""
+    existing = read_workspace_token(workspace)
+    if existing and not rotate:
+        return existing
+    token = generate_token()
+    write_workspace_token(workspace, token)
+    return token
+
+
+def expected_publish_token(workspace: Path | None) -> str | None:
+    """Resolve the token required for publish operations."""
+    if os.environ.get("AGENTBUS_AUTH", "auto").lower() == "off":
+        return None
+    if workspace is not None:
+        file_token = read_workspace_token(workspace)
+        if file_token:
+            return file_token
+    return os.environ.get("AGENTBUS_EXPECTED_TOKEN") or None
+
+
+def provided_publish_token(
+    auth_token: str | None = None,
+    workspace: Path | None = None,
+) -> str:
+    if auth_token:
+        return auth_token
+    if workspace is not None:
+        file_token = read_workspace_token(workspace)
+        if file_token:
+            return file_token
+    env_token = os.environ.get("AGENTBUS_TOKEN", "")
+    if env_token:
+        return env_token
+    return ""
+
+
+def check_publish_token(
+    workspace: Path | None = None,
+    auth_token: str | None = None,
+) -> None:
+    """Require a valid token for publish when auth is configured."""
+    expected = expected_publish_token(workspace)
+    if not expected:
+        return
+    if provided_publish_token(auth_token, workspace) != expected:
+        raise ValueError("unauthorized")

agentbus/cli.py

@@ -0,0 +1,343 @@
+"""AgentBus CLI."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import click
+
+from agentbus.auth import (
+    check_publish_token,
+    ensure_ephemeral_token,
+    read_workspace_token,
+    token_path,
+)
+from agentbus.leases import LeaseStore
+from agentbus.project_log import project_handoffs
+from agentbus.schemas import validate_payload
+from agentbus.server import run_stdio
+from agentbus.store import EventStore
+
+DEFAULT_WORKSPACE = os.environ.get("AGENTBUS_WORKSPACE", str(Path.cwd()))
+
+
+def _producer_id(override: str | None) -> str:
+    pid = override or os.environ.get("AGENTBUS_PRODUCER_ID", "")
+    if not pid:
+        raise click.ClickException("Set --producer-id or AGENTBUS_PRODUCER_ID")
+    return pid
+
+
+def _open_store(workspace: str, retention_days: int) -> EventStore:
+    return EventStore(Path(workspace), retention_days=retention_days)
+
+
+def _open_lease_store(workspace: str) -> LeaseStore:
+    return LeaseStore(Path(workspace))
+
+
+def _auth(ws: Path, token: str | None) -> None:
+    try:
+        check_publish_token(ws, auth_token=token)
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+@click.group()
+def main() -> None:
+    """Local MCP event log for multi-agent workspaces."""
+
+
+@main.command()
+@click.option(
+    "--workspace",
+    type=click.Path(exists=True, file_okay=False, path_type=str),
+    default=DEFAULT_WORKSPACE,
+    show_default=True,
+)
+@click.option("--retention-days", default=7, show_default=True)
+@click.option(
+    "--rotate-token",
+    is_flag=True,
+    help="Regenerate workspace token on startup",
+)
+def serve(workspace: str, retention_days: int, rotate_token: bool) -> None:
+    """Run MCP server on stdio."""
+    run_stdio(Path(workspace), retention_days=retention_days, rotate_token=rotate_token)
+
+
+@main.command()
+@click.option("--workspace", default=DEFAULT_WORKSPACE, show_default=True)
+@click.option("--topic", required=True)
+@click.option("--payload", "payload_json", default=None, help="JSON object string")
+@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False), default=None)
+@click.option("--schema-version", default="1.0", show_default=True)
+@click.option("--producer-id", default=None)
+@click.option("--causation-id", type=int, default=None)
+@click.option("--idempotency-key", default=None)
+@click.option("--token", default=None, help="Publish auth token (default: workspace file)")
+@click.option("--retention-days", default=7, show_default=True)
+def publish(
+    workspace: str,
+    topic: str,
+    payload_json: str | None,
+    payload_file: str | None,
+    schema_version: str,
+    producer_id: str | None,
+    causation_id: int | None,
+    idempotency_key: str | None,
+    token: str | None,
+    retention_days: int,
+) -> None:
+    """Append one event (CLI fallback for non-MCP clients like Agy)."""
+    if payload_file:
+        payload = json.loads(Path(payload_file).read_text(encoding="utf-8"))
+    elif payload_json:
+        payload = json.loads(payload_json)
+    else:
+        raise click.ClickException("Provide --payload or --payload-file")
+
+    ws = Path(workspace)
+    _auth(ws, token)
+    payload = validate_payload(topic, payload)
+    store = _open_store(workspace, retention_days)
+    try:
+        event, duplicate = store.publish(
+            topic=topic,
+            producer_id=_producer_id(producer_id),
+            schema_version=schema_version,
+            payload=payload,
+            causation_id=causation_id,
+            idempotency_key=idempotency_key,
+        )
+        click.echo(
+            json.dumps(
+                {
+                    "event_id": event.event_id,
+                    "topic": event.topic,
+                    "timestamp": event.timestamp,
+                    "duplicate": duplicate,
+                }
+            )
+        )
+    finally:
+        store.close()
+
+
+@main.command()
+@click.option("--workspace", default=DEFAULT_WORKSPACE, show_default=True)
+@click.option("--topic", required=True)
+@click.option("--since-id", type=int, default=0, show_default=True)
+@click.option("--limit", type=int, default=50, show_default=True)
+@click.option("--retention-days", default=7, show_default=True)
+def poll(
+    workspace: str,
+    topic: str,
+    since_id: int,
+    limit: int,
+    retention_days: int,
+) -> None:
+    """Fetch events after cursor."""
+    store = _open_store(workspace, retention_days)
+    try:
+        click.echo(json.dumps(store.poll(topic=topic, since_id=since_id, limit=limit)))
+    finally:
+        store.close()
+
+
+@main.command()
+@click.option("--workspace", default=DEFAULT_WORKSPACE, show_default=True)
+@click.option("--producer-id", default=None)
+@click.option("--retention-days", default=7, show_default=True)
+def status(workspace: str, producer_id: str | None, retention_days: int) -> None:
+    """Workspace bus health."""
+    store = _open_store(workspace, retention_days)
+    try:
+        pid = producer_id or os.environ.get("AGENTBUS_PRODUCER_ID", "")
+        click.echo(json.dumps(store.status(producer_id=pid or None)))
+    finally:
+        store.close()
+
+
+@main.group()
+def lock() -> None:
+    """Advisory lease locks (Phase 5)."""
+
+
+@lock.command("acquire")
+@click.option("--workspace", default=DEFAULT_WORKSPACE, show_default=True)
+@click.option("--resource", required=True, help="Absolute path within workspace")
+@click.option("--owner-id", required=True)
+@click.option("--ttl-seconds", type=int, default=None)
+@click.option("--token", default=None)
+def lock_acquire(
+    workspace: str,
+    resource: str,
+    owner_id: str,
+    ttl_seconds: int | None,
+    token: str | None,
+) -> None:
+    """Acquire a lease on a resource."""
+    ws = Path(workspace)
+    _auth(ws, token)
+    store = _open_lease_store(workspace)
+    try:
+        click.echo(json.dumps(store.lock_acquire(resource, owner_id, ttl_seconds)))
+    finally:
+        store.close()
+
+
+@lock.command("release")
+@click.option("--workspace", default=DEFAULT_WORKSPACE, show_default=True)
+@click.option("--resource", required=True)
+@click.option("--lease-id", required=True)
+@click.option("--owner-id", required=True)
+@click.option("--token", default=None)
+def lock_release(
+    workspace: str,
+    resource: str,
+    lease_id: str,
+    owner_id: str,
+    token: str | None,
+) -> None:
+    """Release a held lease."""
+    ws = Path(workspace)
+    _auth(ws, token)
+    store = _open_lease_store(workspace)
+    try:
+        click.echo(json.dumps(store.lock_release(resource, lease_id, owner_id)))
+    finally:
+        store.close()
+
+
+@lock.command("renew")
+@click.option("--workspace", default=DEFAULT_WORKSPACE, show_default=True)
+@click.option("--resource", required=True)
+@click.option("--lease-id", required=True)
+@click.option("--owner-id", required=True)
+@click.option("--ttl-seconds", type=int, default=None)
+@click.option("--token", default=None)
+def lock_renew(
+    workspace: str,
+    resource: str,
+    lease_id: str,
+    owner_id: str,
+    ttl_seconds: int | None,
+    token: str | None,
+) -> None:
+    """Renew (extend) a held lease."""
+    ws = Path(workspace)
+    _auth(ws, token)
+    store = _open_lease_store(workspace)
+    try:
+        click.echo(json.dumps(store.lock_renew(resource, lease_id, owner_id, ttl_seconds)))
+    finally:
+        store.close()
+
+
+@lock.command("status")
+@click.option("--workspace", default=DEFAULT_WORKSPACE, show_default=True)
+@click.option("--resource", required=True)
+def lock_status(workspace: str, resource: str) -> None:
+    """Check lock state (no auth)."""
+    store = _open_lease_store(workspace)
+    try:
+        click.echo(json.dumps(store.lock_status(resource)))
+    finally:
+        store.close()
+
+
+@main.command("project-log")
+@click.option("--workspace", default=DEFAULT_WORKSPACE, show_default=True)
+@click.option(
+    "--log-file",
+    default="log.md",
+    show_default=True,
+    help="Log file relative to workspace",
+)
+@click.option("--dry-run", is_flag=True, help="Print lines without writing log.md")
+@click.option("--reset", is_flag=True, help="Re-project all events from event_id 0")
+@click.option("--retention-days", default=7, show_default=True)
+def project_log(
+    workspace: str,
+    log_file: str,
+    dry_run: bool,
+    reset: bool,
+    retention_days: int,
+) -> None:
+    """Project okf/handoff events into OKF log.md format."""
+    ws = Path(workspace)
+    log_path = ws / log_file
+    store = _open_store(workspace, retention_days)
+    try:
+        result = project_handoffs(
+            store, ws, log_path, dry_run=dry_run, reset=reset
+        )
+        click.echo(json.dumps({k: v for k, v in result.items() if k != "lines"}))
+        if dry_run and result["lines"]:
+            click.echo("---")
+            click.echo("\n\n".join(result["lines"]))
+    finally:
+        store.close()
+
+
+@main.group()
+def token() -> None:
+    """Workspace ephemeral token management."""
+
+
+@token.command("show")
+@click.option("--workspace", default=DEFAULT_WORKSPACE, show_default=True)
+@click.option("--quiet", is_flag=True, help="Print token only (no path)")
+def token_show(workspace: str, quiet: bool) -> None:
+    """Print the workspace publish token."""
+    ws = Path(workspace)
+    value = read_workspace_token(ws)
+    if not value:
+        raise click.ClickException(
+            f"No token at {token_path(ws)} — run: agentbus token ensure"
+        )
+    if quiet:
+        click.echo(value)
+    else:
+        click.echo(json.dumps({"path": str(token_path(ws)), "token": value}))
+
+
+@token.command("ensure")
+@click.option("--workspace", default=DEFAULT_WORKSPACE, show_default=True)
+@click.option("--quiet", is_flag=True, help="Print token only")
+def token_ensure(workspace: str, quiet: bool) -> None:
+    """Create workspace token if missing."""
+    ws = Path(workspace)
+    value = ensure_ephemeral_token(ws, rotate=False)
+    if quiet:
+        click.echo(value)
+    else:
+        click.echo(
+            json.dumps(
+                {"path": str(token_path(ws)), "token": value, "created": True}
+            )
+        )
+
+
+@token.command("rotate")
+@click.option("--workspace", default=DEFAULT_WORKSPACE, show_default=True)
+@click.option("--quiet", is_flag=True, help="Print token only")
+def token_rotate(workspace: str, quiet: bool) -> None:
+    """Regenerate workspace publish token."""
+    ws = Path(workspace)
+    value = ensure_ephemeral_token(ws, rotate=True)
+    if quiet:
+        click.echo(value)
+    else:
+        click.echo(
+            json.dumps(
+                {"path": str(token_path(ws)), "token": value, "rotated": True}
+            )
+        )
+
+
+if __name__ == "__main__":
+    main()

agentbus/leases.py

@@ -0,0 +1,202 @@
+"""Advisory lease locks — Phase 5 (persisted in events.db)."""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+import uuid
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+DEFAULT_TTL_SECONDS = 300
+MAX_TTL_SECONDS = 3600
+OWNER_PATTERN = re.compile(r"^[a-z][a-z0-9_-]*$")
+
+
+def validate_owner_id(owner_id: str) -> None:
+    if not owner_id or not OWNER_PATTERN.match(owner_id):
+        raise ValueError(f"invalid_owner_id: {owner_id}")
+
+
+def normalize_resource(workspace: Path, resource: str) -> str:
+    if not resource:
+        raise ValueError("invalid_resource: empty path")
+    path = Path(resource).expanduser().resolve()
+    ws = workspace.resolve()
+    try:
+        path.relative_to(ws)
+    except ValueError as exc:
+        raise ValueError(f"resource_outside_workspace: {resource}") from exc
+    return str(path)
+
+
+def clamp_ttl(ttl_seconds: int | None, default: int = DEFAULT_TTL_SECONDS) -> int:
+    if ttl_seconds is None:
+        return default
+    if ttl_seconds < 1:
+        raise ValueError("invalid_ttl: must be >= 1")
+    if ttl_seconds > MAX_TTL_SECONDS:
+        raise ValueError(f"invalid_ttl: max {MAX_TTL_SECONDS}")
+    return ttl_seconds
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _fmt(dt: datetime) -> str:
+    return dt.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _parse(ts: str) -> datetime:
+    return datetime.strptime(ts, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+
+
+class LeaseStore:
+    """Lease locks stored in the workspace events.db `leases` table."""
+
+    def __init__(self, workspace: Path, default_ttl: int = DEFAULT_TTL_SECONDS) -> None:
+        self.workspace = workspace.resolve()
+        self.default_ttl = default_ttl
+        db_dir = self.workspace / ".agentbus"
+        db_dir.mkdir(parents=True, exist_ok=True)
+        self.db_path = db_dir / "events.db"
+        self._conn = sqlite3.connect(self.db_path, check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._init_schema()
+
+    def _init_schema(self) -> None:
+        self._conn.executescript(
+            """
+            CREATE TABLE IF NOT EXISTS leases (
+                lease_id TEXT PRIMARY KEY,
+                resource TEXT NOT NULL UNIQUE,
+                owner_id TEXT NOT NULL,
+                acquired_at TEXT NOT NULL,
+                expires_at TEXT NOT NULL
+            );
+            CREATE INDEX IF NOT EXISTS idx_leases_resource ON leases(resource);
+            CREATE INDEX IF NOT EXISTS idx_leases_expires ON leases(expires_at);
+            """
+        )
+        self._conn.commit()
+
+    def close(self) -> None:
+        self._conn.close()
+
+    def _purge_expired(self) -> None:
+        cutoff = _fmt(_utc_now())
+        self._conn.execute("DELETE FROM leases WHERE expires_at <= ?", (cutoff,))
+        self._conn.commit()
+
+    def _active_row(self, resource: str) -> sqlite3.Row | None:
+        self._purge_expired()
+        return self._conn.execute(
+            "SELECT * FROM leases WHERE resource = ?",
+            (resource,),
+        ).fetchone()
+
+    def lock_acquire(
+        self,
+        resource: str,
+        owner_id: str,
+        ttl_seconds: int | None = None,
+    ) -> dict:
+        validate_owner_id(owner_id)
+        path = normalize_resource(self.workspace, resource)
+        ttl = clamp_ttl(ttl_seconds, self.default_ttl)
+        now = _utc_now()
+        expires = now + timedelta(seconds=ttl)
+
+        existing = self._active_row(path)
+        if existing:
+            if existing["owner_id"] == owner_id:
+                return {
+                    "acquired": True,
+                    "lease_id": existing["lease_id"],
+                    "expires_at": existing["expires_at"],
+                    "resource": path,
+                }
+            return {
+                "acquired": False,
+                "current_owner": existing["owner_id"],
+                "expires_at": existing["expires_at"],
+                "resource": path,
+            }
+
+        lease_id = str(uuid.uuid4())
+        self._conn.execute(
+            """
+            INSERT INTO leases (lease_id, resource, owner_id, acquired_at, expires_at)
+            VALUES (?, ?, ?, ?, ?)
+            """,
+            (lease_id, path, owner_id, _fmt(now), _fmt(expires)),
+        )
+        self._conn.commit()
+        return {
+            "acquired": True,
+            "lease_id": lease_id,
+            "expires_at": _fmt(expires),
+            "resource": path,
+        }
+
+    def lock_release(self, resource: str, lease_id: str, owner_id: str) -> dict:
+        validate_owner_id(owner_id)
+        path = normalize_resource(self.workspace, resource)
+        self._purge_expired()
+        row = self._conn.execute(
+            "SELECT * FROM leases WHERE resource = ? AND lease_id = ?",
+            (path, lease_id),
+        ).fetchone()
+        if not row:
+            return {"released": True, "resource": path}
+        if row["owner_id"] != owner_id:
+            raise ValueError("invalid_owner: owner_id does not hold this lease")
+        self._conn.execute(
+            "DELETE FROM leases WHERE lease_id = ?",
+            (lease_id,),
+        )
+        self._conn.commit()
+        return {"released": True, "resource": path}
+
+    def lock_renew(
+        self,
+        resource: str,
+        lease_id: str,
+        owner_id: str,
+        ttl_seconds: int | None = None,
+    ) -> dict:
+        validate_owner_id(owner_id)
+        path = normalize_resource(self.workspace, resource)
+        ttl = clamp_ttl(ttl_seconds, self.default_ttl)
+        self._purge_expired()
+        row = self._conn.execute(
+            "SELECT * FROM leases WHERE resource = ? AND lease_id = ?",
+            (path, lease_id),
+        ).fetchone()
+        if not row or row["owner_id"] != owner_id:
+            return {"renewed": False, "resource": path}
+        expires = _utc_now() + timedelta(seconds=ttl)
+        self._conn.execute(
+            "UPDATE leases SET expires_at = ? WHERE lease_id = ?",
+            (_fmt(expires), lease_id),
+        )
+        self._conn.commit()
+        return {"renewed": True, "expires_at": _fmt(expires), "resource": path}
+
+    def lock_status(self, resource: str) -> dict:
+        path = normalize_resource(self.workspace, resource)
+        row = self._active_row(path)
+        if not row:
+            return {
+                "locked": False,
+                "resource": path,
+            }
+        return {
+            "locked": True,
+            "resource": path,
+            "lease_id": row["lease_id"],
+            "current_owner": row["owner_id"],
+            "acquired_at": row["acquired_at"],
+            "expires_at": row["expires_at"],
+        }