collab-runtime 0.3.0__tar.gz → 0.4.0__tar.gz

{collab_runtime-0.3.0/collab_runtime.egg-info → collab_runtime-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: collab-runtime
-Version: 0.3.0
+Version: 0.4.0
 Summary: Collaborative file locking runtime
 Author-email: KirilMT <kiril.mt95@gmail.com>
 License-Expression: MIT
@@ -68,7 +68,7 @@ pip install collab-runtime
 For a minimum-version install (ensures you get the latest compatible release):
 
 ```bash
-pip install "collab-runtime>=0.2.2"
+pip install "collab-runtime>=0.3.2"
 ```
 
 ---
@@ -91,10 +91,37 @@ SUPABASE_ANON_KEY=your_anon_key_here
 SUPABASE_SERVICE_ROLE_KEY=your_service_role_key   # Required for force-release
 DEVELOPER_ID=your_name                             # Optional, defaults to git user.name
 LOCK_STRICT=0                                      # 1 = block on lock errors, 0 = warn only
+COLLAB_AGENT_ID=agent-my-task                      # Optional: unique id per AI agent session
+COLLAB_AGENT_LABEL=refactor-auth                   # Optional display label
+COLLAB_AGENT_MODE=1                                # Auto-generate/persist agent id when unset
 ```
 
 > **Keep `SUPABASE_SERVICE_ROLE_KEY` private — never commit it to version control.**
 
+### Multi-agent usage (same GitHub user, multiple AI agents)
+
+When one developer runs several AI agents in the same repo, give each agent its own identity so
+locks do not collide (effective owner is `developer_id` + `agent_id`):
+
+```bash
+# Agent A
+export COLLAB_AGENT_ID=agent-refactor-auth
+collab whoami
+collab acquire src/auth.py --reason "Refactor auth"
+
+# Agent B (different id) — conflicts with A on the same file
+export COLLAB_AGENT_ID=agent-fix-tests
+collab acquire src/auth.py
+```
+
+CLI flags `--agent-id` and `--agent-label` override env vars. Use `collab active --mine` to list
+only locks held by the current human + agent pair.
+
+**Existing Supabase projects:** apply the `agent_id` / `agent_label` columns and updated
+`acquire_lock` function from
+[`supabase/schema.sql`](https://github.com/KirilMT/collab/blob/main/supabase/schema.sql) in the SQL
+Editor (fresh installs already include them).
+
 ### 3 — Verify Connection
 
 ```bash
@@ -108,8 +135,12 @@ If connected, this lists all currently active locks (empty on a fresh setup).
 ## CLI Reference
 
 ```bash
+# Show resolved developer and agent identity
+collab whoami
+
 # Show all active locks across the team
 collab active
+collab active --mine
 
 # Lock a file before editing
 collab acquire path/to/file.py --reason "Implementing feature X"

{collab_runtime-0.3.0 → collab_runtime-0.4.0}/README.md

@@ -74,15 +74,38 @@ The setup script automatically:
 
 After setup, verify your `.env` at the project root has these values:
 
-| Variable                    | Description                                                     |
-| --------------------------- | --------------------------------------------------------------- |
-| `SUPABASE_URL`              | Your Supabase project URL (from Project Settings → API)         |
-| `SUPABASE_ANON_KEY`         | Anonymous/public key (from Project Settings → API)              |
-| `SUPABASE_SERVICE_ROLE_KEY` | Service role key (**required** for dashboard force-release)     |
-| `LOCK_STRICT`               | If `1`, git hooks block on lock errors. Default `0` (warn only) |
+| Variable                    | Description                                                      |
+| --------------------------- | ---------------------------------------------------------------- |
+| `SUPABASE_URL`              | Your Supabase project URL (from Project Settings → API)          |
+| `SUPABASE_ANON_KEY`         | Anonymous/public key (from Project Settings → API)               |
+| `SUPABASE_SERVICE_ROLE_KEY` | Service role key (**required** for dashboard force-release)      |
+| `LOCK_STRICT`               | If `1`, git hooks block on lock errors. Default `0` (warn only)  |
+| `COLLAB_AGENT_ID`           | Optional stable id for an AI agent session (multi-agent locking) |
+| `COLLAB_AGENT_LABEL`        | Optional display label (e.g. `refactor-auth`)                    |
+| `COLLAB_AGENT_MODE`         | Set to `1` to auto-generate/persist an agent id when unset       |
 
 > **Important:** `SUPABASE_SERVICE_ROLE_KEY` is needed for the dashboard's Force Release button. Without it, only your own locks can be released.
 
+### Multi-agent usage (same GitHub user, multiple AI agents)
+
+When one developer runs several AI agents in the same repo, give each agent its own identity so
+locks do not collide:
+
+```bash
+# Terminal / agent A
+set COLLAB_AGENT_ID=agent-refactor-auth
+collab whoami
+collab acquire src/auth.py --reason "Refactor auth"
+
+# Terminal / agent B (different id)
+set COLLAB_AGENT_ID=agent-fix-tests
+collab acquire src/auth.py   # conflict — locked by agent-refactor-auth
+```
+
+For existing Supabase projects, re-run the `acquire_lock` function and add the `agent_id` /
+`agent_label` columns from the updated [supabase/schema.sql](supabase/schema.sql) (fresh installs
+already include them).
+
 ### 4. Verify Setup
 
 After setup, verify the connection:

collab_runtime-0.4.0/collab/agent_identity.py

@@ -0,0 +1,293 @@
+"""Agent identity resolution for multi-agent collaborative locking.
+
+When one GitHub user runs multiple AI agents in the same repository, each agent needs a
+stable, unique identity layered on top of the human ``developer_id``. This module
+resolves ``agent_id`` / ``agent_label`` and provides helpers for lock ownership
+comparisons.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import uuid
+from typing import Any, Optional
+
+_AGENT_ID_FILE = ".agent_id"
+_AGENT_LABEL_FILE = ".agent_label"
+_AGENT_ID_PATTERN = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$")
+
+# Environment variables that imply an AI agent runtime (not exhaustive).
+_AGENT_RUNTIME_MARKERS: tuple[tuple[str, str], ...] = (
+    ("CURSOR_TRACE_ID", "cursor"),
+    ("CURSOR_SESSION_ID", "cursor"),
+    ("CURSOR_AGENT", "cursor"),
+    ("COMPOSER_SESSION_ID", "composer"),
+    ("CLAUDE_CODE", "claude-code"),
+    ("CLAUDE_CODE_SESSION", "claude-code"),
+    ("GITHUB_COPILOT_AGENT_ID", "copilot"),
+)
+
+
+def _read_clean_env(name: str) -> Optional[str]:
+    raw = os.getenv(name)
+    if raw is None:
+        return None
+    val = raw.strip()
+    if not val or val.startswith("#"):
+        return None
+    if "#" in val:
+        val = val.split("#", 1)[0].strip()
+    return val or None
+
+
+def _is_truthy_env(name: str) -> bool:
+    raw = _read_clean_env(name)
+    if raw is None:
+        return False
+    return raw.lower() in {"1", "true", "yes", "on"}
+
+
+def detect_agent_runtime_label() -> Optional[str]:
+    """Return a friendly runtime label when known agent env markers are present."""
+    for env_name, label in _AGENT_RUNTIME_MARKERS:
+        if _read_clean_env(env_name):
+            return label
+    return None
+
+
+def is_agent_mode_requested() -> bool:
+    """Return True when agent identity should be active for this process."""
+    if _read_clean_env("COLLAB_AGENT_ID"):
+        return True
+    if _is_truthy_env("COLLAB_AGENT_MODE"):
+        return True
+    if detect_agent_runtime_label():
+        return True
+    return False
+
+
+def _sanitize_agent_id(value: str) -> Optional[str]:
+    candidate = value.strip()
+    if not candidate or not _AGENT_ID_PATTERN.match(candidate):
+        return None
+    return candidate
+
+
+def _agent_id_file(state_dir: str) -> str:
+    return os.path.join(state_dir, _AGENT_ID_FILE)
+
+
+def load_persisted_agent_id(state_dir: str) -> Optional[str]:
+    """Load a previously persisted agent id from the collab state directory."""
+    path = _agent_id_file(state_dir)
+    try:
+        if not os.path.isfile(path):
+            return None
+        with open(path, encoding="utf-8") as fh:
+            raw = fh.read().strip()
+        return _sanitize_agent_id(raw) if raw else None
+    except OSError:
+        return None
+
+
+def persist_agent_id(state_dir: str, agent_id: str) -> None:
+    """Persist agent id so subsequent invocations in this state dir reuse it."""
+    os.makedirs(state_dir, exist_ok=True)
+    path = _agent_id_file(state_dir)
+    tmp = f"{path}.tmp"
+    with open(tmp, "w", encoding="utf-8") as fh:
+        fh.write(agent_id)
+        fh.flush()
+        try:
+            os.fsync(fh.fileno())
+        except OSError:
+            pass
+    os.replace(tmp, path)
+
+
+def generate_agent_id() -> str:
+    """Generate a stable-format unique agent id."""
+    return f"agent-{uuid.uuid4().hex[:8]}"
+
+
+def resolve_agent_id(
+    state_dir: str,
+    *,
+    explicit_agent_id: Optional[str] = None,
+    agent_mode: Optional[bool] = None,
+) -> Optional[str]:
+    """Resolve agent id using precedence: explicit env/arg → persisted → generated.
+
+    Returns ``None`` when agent mode is off (human-only locking).
+    """
+    mode = is_agent_mode_requested() if agent_mode is None else agent_mode
+    if explicit_agent_id or _read_clean_env("COLLAB_AGENT_ID"):
+        mode = True
+    if not mode:
+        return None
+
+    for candidate in (
+        explicit_agent_id,
+        _read_clean_env("COLLAB_AGENT_ID"),
+    ):
+        if candidate:
+            sanitized = _sanitize_agent_id(candidate)
+            if sanitized:
+                persist_agent_id(state_dir, sanitized)
+                return sanitized
+
+    persisted = load_persisted_agent_id(state_dir)
+    if persisted:
+        return persisted
+
+    generated = generate_agent_id()
+    persist_agent_id(state_dir, generated)
+    return generated
+
+
+def resolve_agent_label(
+    *,
+    explicit_label: Optional[str] = None,
+    runtime_label: Optional[str] = None,
+) -> Optional[str]:
+    """Resolve optional human-readable agent label."""
+    for candidate in (
+        explicit_label,
+        _read_clean_env("COLLAB_AGENT_LABEL"),
+        runtime_label,
+        detect_agent_runtime_label(),
+    ):
+        if candidate:
+            val = candidate.strip()
+            if val:
+                return val[:256]
+    return None
+
+
+def agent_ids_match(
+    lock_agent_id: Optional[str],
+    client_agent_id: Optional[str],
+) -> bool:
+    """Return True when two agent_id values represent the same lock owner."""
+    return (lock_agent_id or None) == (client_agent_id or None)
+
+
+def lock_owned_by_client(
+    lock: dict[str, Any],
+    developer_id: str,
+    agent_id: Optional[str],
+) -> bool:
+    """Return True when *lock* belongs to the given human + agent pair."""
+    if lock.get("developer_id") != developer_id:
+        return False
+    return agent_ids_match(lock.get("agent_id"), agent_id)
+
+
+def format_lock_owner(
+    developer_id: str,
+    agent_id: Optional[str] = None,
+    agent_label: Optional[str] = None,
+) -> str:
+    """Format lock owner for CLI/log messages."""
+    base = f"@{developer_id}"
+    if agent_id:
+        label = agent_label or agent_id
+        return f"{base} (agent: {label})"
+    return base
+
+
+def format_conflict_message(
+    file_path: str,
+    developer_id: str,
+    agent_id: Optional[str] = None,
+    agent_label: Optional[str] = None,
+) -> str:
+    """Build a user-facing conflict message."""
+    owner = format_lock_owner(developer_id, agent_id, agent_label)
+    return f"⚠ {file_path} is locked by {owner}. Editing is not recommended."
+
+
+def session_token_seed(
+    developer_id: str,
+    agent_id: Optional[str],
+    hostname: str,
+    project_root: str,
+) -> str:
+    """Build the seed string for deterministic session tokens.
+
+    Each component derivation is defensive: if a value cannot be stringified, a safe
+    fallback is used rather than raising (a raised seed breaks re-adoption).
+    """
+    try:
+        dev = str(developer_id).strip().lower() if developer_id else "unknown"
+    except Exception:
+        dev = "unknown"
+    try:
+        host = hostname.lower() if hostname else "localhost"
+    except Exception:
+        host = "localhost"
+    try:
+        root = project_root.lower().rstrip("\\/") if project_root else "project"
+    except Exception:
+        root = "project"
+    if agent_id:
+        try:
+            agent = str(agent_id).strip().lower()
+        except Exception:
+            agent = "agent"
+        return f"{dev}:{agent}:{host}:{root}"
+    return f"{dev}:{host}:{root}"
+
+
+def session_token_from_seed(seed: str) -> str:
+    """Derive the 16-char hex session token from a seed."""
+    return hashlib.sha256(seed.encode()).hexdigest()[:16]
+
+
+def daemon_pid_basename(agent_id: Optional[str]) -> str:
+    """Return the daemon PID filename for the given agent (or default)."""
+    if not agent_id:
+        return ".daemon.pid"
+    safe = re.sub(r"[^a-zA-Z0-9._-]", "_", agent_id)
+    return f".daemon.{safe}.pid"
+
+
+def resolve_daemon_pid_path(
+    state_dir: str,
+    agent_id: Optional[str],
+    *,
+    env_override: Optional[str] = None,
+) -> str:
+    """Resolve the PID file path for a watcher instance."""
+    override = env_override or _read_clean_env("COLLAB_PID_FILE")
+    if override:
+        return override
+    return os.path.join(state_dir, daemon_pid_basename(agent_id))
+
+
+def apply_agent_filter(query: Any, agent_id: Optional[str]) -> Any:
+    """Scope a PostgREST delete/update query to the current agent_id (or NULL)."""
+    if agent_id is None:
+        is_null = getattr(query, "is_", None)
+        if callable(is_null):
+            return is_null("agent_id", "null")
+        # Test doubles may only implement ``eq`` — treat NULL as None there.
+        return query.eq("agent_id", None)
+    return query.eq("agent_id", agent_id)
+
+
+def identity_summary(
+    developer_id: str,
+    agent_id: Optional[str],
+    agent_label: Optional[str],
+) -> dict[str, Optional[str]]:
+    """Return a dict suitable for ``collab whoami`` JSON output."""
+    mode = "agent" if agent_id else "human"
+    return {
+        "developer_id": developer_id,
+        "agent_id": agent_id,
+        "agent_label": agent_label,
+        "mode": mode,
+    }