collab-runtime 0.4.2__tar.gz → 0.5.1__tar.gz

{collab_runtime-0.4.2/collab_runtime.egg-info → collab_runtime-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: collab-runtime
-Version: 0.4.2
+Version: 0.5.1
 Summary: Collaborative file locking runtime
 Author-email: KirilMT <kiril.mt95@gmail.com>
 License-Expression: MIT
@@ -130,6 +130,19 @@ collab active
 
 If connected, this lists all currently active locks (empty on a fresh setup).
 
+### 4 — Install Git Hooks (optional)
+
+```bash
+collab init-hooks
+```
+
+This installs `pre-commit`, `post-commit`, `pre-push`, and `commit-msg` hooks into the current
+repository. The hooks acquire locks for staged files, block commits that conflict with another
+developer's lock, and release locks after a successful push. They resolve the project `.venv` first,
+so **commits from VS Code / Cursor Source Control behave the same as a venv-activated terminal**.
+
+Existing non-collab hooks are preserved; pass `--force` to overwrite them.
+
 ---
 
 ## CLI Reference
@@ -162,6 +175,10 @@ collab force-release-all
 collab acquire-batch path/to/a.py path/to/b.py --reason "Refactoring"
 collab release-batch path/to/a.py path/to/b.py
 
+# Install git hooks into the current repo (offline)
+collab init-hooks
+collab init-hooks --force
+
 # Reconcile local and remote lock state
 collab reconcile
 

{collab_runtime-0.4.2 → collab_runtime-0.5.1}/README.md

@@ -74,15 +74,18 @@ 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)  |
-| `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       |
+| 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 task label shown on the dashboard (e.g. `refactor-auth`)   |
+| `COLLAB_AGENT_KIND`         | Optional AI runtime for the dashboard icon (auto-detected)          |
+| `COLLAB_AGENT_MODE`         | Set to `1` to auto-generate/persist an agent id when unset          |
+| `COLLAB_AGENT_HOOKS`        | Set to `1` to enable the IDE edit hook that auto-claims agent edits |
+| `COLLAB_WATCHER_AGENT_ID`   | Opt in to a dedicated agent watcher (default: watcher = human)      |
 
 > **Important:** `SUPABASE_SERVICE_ROLE_KEY` is needed for the dashboard's Force Release button. Without it, only your own locks can be released.
 
@@ -102,9 +105,28 @@ 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).
+For existing Supabase projects, re-run [supabase/schema.sql](supabase/schema.sql) to add the
+`agent_id` / `agent_label` / `origin` / `agent_kind` columns and the updated `acquire_lock` function
+(the script is idempotent; fresh installs already include them).
+
+#### Strict user-vs-agent attribution
+
+The dashboard distinguishes **human** edits from **AI agent** edits and shows _what the agent is
+working on_ — not a cryptic id. Attribution is decided by an explicit signal:
+
+- The background watcher locks bulk git changes as the **human** (`User` chip), even inside an AI
+  IDE. So normal work is never mislabelled as an agent.
+- An AI agent claims the files it edits, producing an **"AI Agent"** badge (runtime icon + task).
+  Make this automatic by wiring your IDE's edit hook to `collab claim` — see
+  [scripts/agent-hooks/](scripts/agent-hooks/README.md). It is **runtime-agnostic** (Cursor, Claude
+  Code, Copilot, Gemini, ...). Enable with `COLLAB_AGENT_HOOKS=1` and optionally
+  `COLLAB_AGENT_LABEL="<task>"`.
+
+Agents can also claim explicitly:
+
+```bash
+collab claim src/auth.py --label "refactor-auth" --reason "Refactor auth"
+```
 
 ### 4. Verify Setup
 

{collab_runtime-0.4.2 → collab_runtime-0.5.1}/collab/agent_identity.py

@@ -58,13 +58,19 @@ def detect_agent_runtime_label() -> Optional[str]:
 
 
 def is_agent_mode_requested() -> bool:
-    """Return True when agent identity should be active for this process."""
+    """Return True when agent identity should be active for this process.
+
+    STRICT ATTRIBUTION: the mere *presence* of an AI runtime (e.g. a process
+    spawned from a Cursor/Claude terminal that exports ``CURSOR_TRACE_ID``) does
+    NOT by itself attribute locks to an agent. Doing so caused every background
+    auto-lock to be mislabelled as the runtime. Agent attribution now requires an
+    *explicit* signal: ``COLLAB_AGENT_ID`` or ``COLLAB_AGENT_MODE``. The detected
+    runtime is still used for friendly display only (see :func:`resolve_agent_kind`).
+    """
     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
 
 
@@ -152,12 +158,17 @@ def resolve_agent_label(
     explicit_label: Optional[str] = None,
     runtime_label: Optional[str] = None,
 ) -> Optional[str]:
-    """Resolve optional human-readable agent label."""
+    """Resolve the human-readable *task* label (the "why / what for").
+
+    This intentionally does NOT fall back to the runtime name (e.g. ``cursor``): the
+    label describes the task an agent is working on (``fix-ci-dashboard``), while the
+    runtime family is tracked separately as ``agent_kind`` for display. When no task
+    label is supplied the dashboard shows a generic "AI Agent".
+    """
     for candidate in (
         explicit_label,
         _read_clean_env("COLLAB_AGENT_LABEL"),
         runtime_label,
-        detect_agent_runtime_label(),
     ):
         if candidate:
             val = candidate.strip()
@@ -166,6 +177,40 @@ def resolve_agent_label(
     return None
 
 
+def resolve_agent_kind(
+    *,
+    explicit_kind: Optional[str] = None,
+    agent_id: Optional[str] = None,
+) -> Optional[str]:
+    """Resolve the AI runtime family for friendly display (icon/name).
+
+    Precedence: explicit value → ``COLLAB_AGENT_KIND`` → detected runtime marker.
+    When an agent identity exists but the runtime is unknown, falls back to the
+    generic ``"other"`` so the dashboard can still render an AI badge. Returns
+    ``None`` for human (no agent) locks.
+    """
+    for candidate in (
+        explicit_kind,
+        _read_clean_env("COLLAB_AGENT_KIND"),
+        detect_agent_runtime_label(),
+    ):
+        if candidate:
+            val = candidate.strip().lower()
+            if val:
+                return val[:64]
+    if agent_id:
+        return "other"
+    return None
+
+
+def resolve_origin(agent_id: Optional[str]) -> str:
+    """Return the authoritative attribution origin for a lock.
+
+    ``'agent'`` when a unique agent identity is present, otherwise ``'human'``.
+    """
+    return "agent" if agent_id else "human"
+
+
 def agent_ids_match(
     lock_agent_id: Optional[str],
     client_agent_id: Optional[str],
@@ -282,6 +327,7 @@ def identity_summary(
     developer_id: str,
     agent_id: Optional[str],
     agent_label: Optional[str],
+    agent_kind: Optional[str] = None,
 ) -> dict[str, Optional[str]]:
     """Return a dict suitable for ``collab whoami`` JSON output."""
     mode = "agent" if agent_id else "human"
@@ -289,5 +335,6 @@ def identity_summary(
         "developer_id": developer_id,
         "agent_id": agent_id,
         "agent_label": agent_label,
+        "agent_kind": agent_kind,
         "mode": mode,
     }

{collab_runtime-0.4.2 → collab_runtime-0.5.1}/collab/dashboard/index.html

@@ -324,6 +324,55 @@
             color: #4338ca;
         }
 
+        /* Human vs AI actor attribution badges */
+        .actor-chip {
+            display: inline-flex;
+            align-items: center;
+            gap: 0.3rem;
+            margin-left: 0.4rem;
+            padding: 0.12rem 0.5rem;
+            border-radius: 999px;
+            font-size: 0.72rem;
+            font-weight: 600;
+            white-space: nowrap;
+            vertical-align: middle;
+        }
+
+        .user-chip {
+            background: #f1f5f9;
+            color: #475569;
+            border: 1px solid var(--border-color);
+        }
+
+        .agent-badge {
+            background: linear-gradient(135deg, #ede9fe 0%, #e0e7ff 100%);
+            color: #5b21b6;
+            border: 1px solid #ddd6fe;
+        }
+
+        .agent-badge-owner {
+            background: linear-gradient(135deg, #ddd6fe 0%, #c7d2fe 100%);
+            color: #4c1d95;
+            border-color: #c4b5fd;
+        }
+
+        .agent-badge .agent-badge-kind {
+            font-weight: 700;
+            text-transform: capitalize;
+        }
+
+        .agent-badge .agent-badge-task {
+            font-weight: 500;
+            opacity: 0.85;
+            max-width: 16rem;
+            overflow: hidden;
+            text-overflow: ellipsis;
+        }
+
+        .agent-badge .agent-badge-sep {
+            opacity: 0.5;
+        }
+
         code {
             color: #1d4ed8;
             background: #f8fafc;
@@ -759,20 +808,98 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
             return !!(SUPABASE_USER && lock.developer_id === SUPABASE_USER);
         }
 
+        function escapeHtml(value) {
+            return String(value == null ? "" : value)
+                .replace(/&/g, "&amp;")
+                .replace(/</g , "&lt;") .replace( />/g, "&gt;")
+                .replace(/"/g, "&quot;")
+                .replace(/'/g, "&#39;");
+        }
+
+        function isAgentLock(lock) {
+            if (lock.origin === "agent") {
+                return true;
+            }
+            // Backward compatibility for rows created before `origin` existed.
+            return !!lock.agent_id && lock.origin !== "human";
+        }
+
+        function agentKindIcon(kind) {
+            switch (String(kind || "").toLowerCase()) {
+                case "cursor":
+                    return '<i class="fas fa-i-cursor"></i>';
+                case "copilot":
+                    return '<i class="fab fa-github"></i>';
+                case "claude-code":
+                case "claude":
+                case "composer":
+                case "other":
+                default:
+                    return '<i class="fas fa-robot"></i>';
+            }
+        }
+
+        function prettifyKind(kind) {
+            const k = String(kind || "").trim();
+            if (!k || k === "other") {
+                return "";
+            }
+            return k
+                .split(/[-_]/)
+                .map((p) => (p ? p.charAt(0).toUpperCase() + p.slice(1) : p))
+                .join(" ");
+        }
+
         function formatDeveloperCell(lock) {
             const dev = lock.developer_id || "?";
-            const agentText = lock.agent_label || lock.agent_id;
-            const chip = agentText
-                ? '<span class="agent-chip' + (lockOwnedByMe(lock) ? " agent-chip-owner" : "") + '">' +
-                  agentText +
-                  "</span>"
-                : '<span class="agent-chip">user</span>';
-            return (
+            const devTag =
                 '<span class="dev-tag ' + (lockOwnedByMe(lock) ? "dev-tag-owner" : "") + '">' +
-                dev +
-                "</span>" +
-                chip
-            );
+                escapeHtml(dev) +
+                "</span>";
+
+            if (!isAgentLock(lock)) {
+                const userChip =
+                    '<span class="actor-chip user-chip" title="Edited by a human developer">' +
+                    '<i class="fas fa-user"></i>User</span>';
+                return devTag + userChip;
+            }
+
+            // AI agent lock: show clearly that it was an AI agent and what for.
+            // The raw agent_id is intentionally never displayed in the cell — it
+            // appears only in the hover tooltip for debugging.
+            const kind = lock.agent_kind || "";
+            const kindName = prettifyKind(kind);
+            const task = String(lock.agent_label || "").trim();
+
+            const tip = ["Edited by an AI agent"];
+            if (kindName) tip.push("Runtime: " + kindName);
+            if (task) tip.push("Task: " + task);
+            if (lock.agent_id) tip.push("Agent id: " + lock.agent_id);
+            if (lock.reason) tip.push("Reason: " + lock.reason);
+
+            let inner =
+                agentKindIcon(kind) + '<span class="agent-badge-text">AI Agent</span>';
+            if (kindName) {
+                inner +=
+                    '<span class="agent-badge-sep">·</span>' +
+                    '<span class="agent-badge-kind">' +
+                    escapeHtml(kindName) +
+                    "</span>";
+            }
+            if (task) {
+                inner +=
+                    '<span class="agent-badge-sep">·</span>' +
+                    '<span class="agent-badge-task">' +
+                    escapeHtml(task) +
+                    "</span>";
+            }
+
+            const badge =
+                '<span class="actor-chip agent-badge' + (lockOwnedByMe(lock) ? " agent-badge-owner" : "") + '" title="' + escapeHtml(tip.join("\n")) + '">' +
+                inner +
+                "</span>";
+
+            return devTag + badge;
         }
 
         function updateTimestamp() {

{collab_runtime-0.4.2 → collab_runtime-0.5.1}/collab/dashboard_server.py

@@ -161,6 +161,7 @@ def load_runtime_supabase_config(project_root: str) -> dict[str, Any]:
     state_dir = state_override or os.path.join(project_root, ".collab")
     agent_id = agent_identity.resolve_agent_id(state_dir)
     agent_label = agent_identity.resolve_agent_label()
+    agent_kind = agent_identity.resolve_agent_kind(agent_id=agent_id)
     project_name = resolve_project_display_name(project_root, file_vals)
     return {
         "url": url,
@@ -169,6 +170,7 @@ def load_runtime_supabase_config(project_root: str) -> dict[str, Any]:
         "user": user,
         "agentId": agent_id,
         "agentLabel": agent_label,
+        "agentKind": agent_kind,
         "projectName": project_name,
     }