pixie-lab-dibs 0.2.0__tar.gz → 0.2.1__tar.gz

{pixie_lab_dibs-0.2.0 → pixie_lab_dibs-0.2.1}/CHANGELOG.md

@@ -10,6 +10,14 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-10-27
+
+### Added
+
+- `GET /agents` explains the server to whoever is pointed at it: setup
+  with this server's URL filled in, what is claimed right now, and the
+  agent skill's rules. The web page links to it.
+
 ## [0.2.0] - 2026-10-27
 
 ### Added

{pixie_lab_dibs-0.2.0 → pixie_lab_dibs-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pixie-lab-dibs
-Version: 0.2.0
+Version: 0.2.1
 Summary: Call dibs on shared lab machines: see who is using what, claim it, release it
 Project-URL: Homepage, https://github.com/safl/pixie-lab-dibs
 Author-email: "Simon A. F. Lund" <os@safl.dk>
@@ -167,6 +167,12 @@ the thing (`bmc = "10.20.30.82"`) rather than a part.
 
 ### AI-agents
 
+Every dibs server explains itself at `/agents`: how to set up for this
+very server, with its URL filled in, what is claimed right now, and the
+rules below. So the one thing to tell a person or an agent about a lab
+is "before touching its machines, read `http://dibs:8090/agents`", in a
+prompt, a project's `AGENTS.md`, or a message.
+
 For Claude Code, install the skill that teaches an agent all of this,
 and it applies whenever the agent is about to use a lab machine:
 
@@ -257,6 +263,7 @@ no login; claim and release take `Authorization: Bearer <token>`.
 | `POST /auth/register`      | `{"user": "...", "pubkey": "ssh-ed25519 ..."}`                                               |
 | `POST /auth/challenge`     | `{"user": "..."}` gives a nonce and the message to sign                                      |
 | `POST /auth/login`         | `{"user", "nonce", "signature"}` gives a token                                               |
+| `GET /agents`              | how to use this server, for a person or an agent, as text                                    |
 | `GET /login.sh`            | the login hook                                                                               |
 
 A claim or release blocked by someone else's claim answers 409 with

{pixie_lab_dibs-0.2.0 → pixie_lab_dibs-0.2.1}/README.md

@@ -145,6 +145,12 @@ the thing (`bmc = "10.20.30.82"`) rather than a part.
 
 ### AI-agents
 
+Every dibs server explains itself at `/agents`: how to set up for this
+very server, with its URL filled in, what is claimed right now, and the
+rules below. So the one thing to tell a person or an agent about a lab
+is "before touching its machines, read `http://dibs:8090/agents`", in a
+prompt, a project's `AGENTS.md`, or a message.
+
 For Claude Code, install the skill that teaches an agent all of this,
 and it applies whenever the agent is about to use a lab machine:
 
@@ -235,6 +241,7 @@ no login; claim and release take `Authorization: Bearer <token>`.
 | `POST /auth/register`      | `{"user": "...", "pubkey": "ssh-ed25519 ..."}`                                               |
 | `POST /auth/challenge`     | `{"user": "..."}` gives a nonce and the message to sign                                      |
 | `POST /auth/login`         | `{"user", "nonce", "signature"}` gives a token                                               |
+| `GET /agents`              | how to use this server, for a person or an agent, as text                                    |
 | `GET /login.sh`            | the login hook                                                                               |
 
 A claim or release blocked by someone else's claim answers 409 with

{pixie_lab_dibs-0.2.0 → pixie_lab_dibs-0.2.1}/src/dibs/__init__.py

@@ -12,4 +12,4 @@ everyone who is on a machine, and it never stops anyone from logging
 in.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

pixie_lab_dibs-0.2.1/src/dibs/_skill.py

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""The agent skill, shared by ``dibs skill`` and the server's ``/agents``
+page, so both say exactly the same thing."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+SKILL_PATH = Path(__file__).parent / "skill" / "SKILL.md"
+
+# The YAML frontmatter Claude Code reads, then the REUSE comment.
+_PREAMBLE = re.compile(r"\A---\n.*?\n---\n\s*<!--.*?-->\s*", re.DOTALL)
+
+
+def skill_text() -> str:
+    """The skill as Claude Code installs it."""
+    return SKILL_PATH.read_text()
+
+
+def skill_body() -> str:
+    """The protocol alone, for readers that are not Claude Code."""
+    return _PREAMBLE.sub("", skill_text(), count=1)

{pixie_lab_dibs-0.2.0 → pixie_lab_dibs-0.2.1}/src/dibs/app.py

@@ -30,6 +30,7 @@ from fastapi.responses import HTMLResponse, PlainTextResponse, Response
 from pydantic import BaseModel, Field
 
 import dibs
+from dibs._skill import skill_body
 from dibs._sources import Config, PixieSource, load_config, sync
 from dibs._store import Claim, ClaimConflict, Store, Thing, covering, describe, sentence
 from dibs._users import DuplicateUser, LoginFailed, NotApproved, UsersStore
@@ -297,6 +298,16 @@ def create_app(
         login. It points back at whichever dibs URL fetched it."""
         return PlainTextResponse(LOGIN_HOOK.format(base=str(request.base_url)))
 
+    @app.get("/agents", response_class=PlainTextResponse)
+    def agents(request: Request) -> PlainTextResponse:
+        """How to use dibs on this lab, for a person or an agent pointed at
+        it: the setup with this server's URL filled in, what is claimed
+        right now, then the protocol from the agent skill."""
+        base = str(request.base_url).rstrip("/")
+        now_lines = "\n".join(f"- {t['sentence']}" for t in list_things()["things"])
+        page = AGENTS_PAGE.format(base=base, now=now_lines or "- nothing to claim yet")
+        return PlainTextResponse(page + "\n" + skill_body(), media_type="text/plain; charset=utf-8")
+
     @app.get("/", response_class=HTMLResponse)
     def index() -> HTMLResponse:
         rows = list_things()["things"]
@@ -337,6 +348,30 @@ case $- in *i*)
 esac
 """
 
+AGENTS_PAGE = """\
+# dibs on this lab
+
+The machines on this lab are shared by people, ai-agents and
+automation-runners, and claimed with dibs at {base}. Read this before you
+touch any of them.
+
+## Set up, once per machine you work from
+
+```
+uv tool install pixie-lab-dibs
+export DIBS_URL={base}
+dibs register <your name>      # then ask the lab's admin to approve you
+dibs login
+```
+
+An agent uses its human's login and needs none of its own. For Claude
+Code, `dibs skill install` makes the rules below load by themselves.
+
+## Right now
+
+{now}
+"""
+
 PAGE = """<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><title>dibs</title>
 <meta name="viewport" content="width=device-width, initial-scale=1">
@@ -347,7 +382,8 @@ td, th {{ text-align: left; padding: .4rem .6rem; border-bottom: 1px solid #ddd;
 </style></head><body>
 <h1>dibs</h1>
 <p>Who is using which thing. Claim one with
-<code>dibs claim &lt;name&gt; --for &lt;purpose&gt;</code>.</p>
+<code>dibs claim &lt;name&gt; --for &lt;purpose&gt;</code>.
+New here, or an agent? Read <a href="/agents">/agents</a>.</p>
 <table><thead><tr><th>Name</th><th>Kind</th><th>Claim</th></tr></thead>
 <tbody>
 {rows}

{pixie_lab_dibs-0.2.0 → pixie_lab_dibs-0.2.1}/src/dibs/cli.py

@@ -550,13 +550,13 @@ def cmd_admin_revoke(args: argparse.Namespace) -> None:
 
 # ---- agent skill -----------------------------------------------------------
 
-SKILL = Path(__file__).parent / "skill" / "SKILL.md"
-
 
 def cmd_skill(args: argparse.Namespace) -> None:
     """Install the Claude Code skill that teaches an agent to claim
     machines before using them, or print it for another agent's setup."""
-    text = SKILL.read_text()
+    from dibs._skill import skill_text
+
+    text = skill_text()
     if args.action == "print":
         sys.stdout.write(text)
         return

{pixie_lab_dibs-0.2.0 → pixie_lab_dibs-0.2.1}/tests/test_app.py

@@ -176,3 +176,18 @@ def test_parts_over_the_api(client: TestClient, tokens, tmp_path: Path) -> None:
     # The login hook on ryzen-01 (by MAC) sees the part's claim.
     hook = client.get("/claim", params={"mac": "aa:bb:cc:dd:ee:60"}).text
     assert hook.startswith("'bob' has claimed 'ryzen-01.bmc'")
+
+
+def test_agents_page_is_set_up_for_this_server(client: TestClient, tokens) -> None:
+    from dibs._skill import skill_body
+
+    _claim(client, tokens, "warp")
+    r = client.get("/agents")
+    assert r.headers["content-type"].startswith("text/plain")
+    page = r.text
+    assert "export DIBS_URL=http://testserver\n" in page
+    assert "- 'alice' has claimed 'warp' for 'xnvme' expires in: 'never'" in page
+    assert page.endswith(skill_body())
+    # The skill's Claude Code frontmatter and licence comment are not for this reader.
+    assert "name: dibs" not in page and "SPDX" not in page
+    assert '<a href="/agents">' in client.get("/").text

{pixie_lab_dibs-0.2.0 → pixie_lab_dibs-0.2.1}/tests/test_cli.py

@@ -285,3 +285,11 @@ def test_skill_ships_in_the_wheel(tmp_path: Path) -> None:
     )
     wheel = next(tmp_path.glob("*.whl"))
     assert "dibs/skill/SKILL.md" in zipfile.ZipFile(wheel).namelist()
+
+
+def test_skill_body_drops_only_the_preamble() -> None:
+    from dibs._skill import skill_body, skill_text
+
+    body = skill_body()
+    assert body.startswith("# Claim lab machines with dibs\n")
+    assert skill_text().endswith(body)