docket-client 0.3.2__py3-none-any.whl

docket_mcp/tools.py

@@ -0,0 +1,1202 @@
+"""The MCP tools: plain methods on `DocketTools`, registered by ``server.py``.
+
+Read tools are anonymous. Every write tool takes ``dry_run`` (default true): a dry run asks the
+server's preview endpoint (or, where the API has none, checks the schedule here) and returns what
+would happen; only ``dry_run=false`` changes anything. Times in and out are local wall-clock plus
+an IANA zone, with UTC alongside; see ``times.py``.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime, timedelta
+from typing import Annotated, Any, Literal
+from zoneinfo import ZoneInfo
+
+from pydantic import BaseModel, Field
+
+from .api import DocketApi, DocketToolError
+from .slots import busy_intervals, free_slots
+from .times import (
+    day_bounds,
+    describe,
+    format_utc,
+    get_zone,
+    parse_date,
+    parse_instant,
+    parse_local_datetime,
+    parse_time,
+)
+
+__all__ = ["TOOL_NAMES", "DocketTools", "Person"]
+
+DRY_RUN_NOTE = (
+    "Call with dry_run=true first and show the user the preview; "
+    "only call again with dry_run=false once they agree."
+)
+NEXT_STEP = (
+    "Show this preview to the user. If they agree, call again with the same arguments and "
+    "dry_run=false, plus the expected_version and idempotency_key from this preview (confirm_with)."
+)
+
+Weekday = Literal["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"]
+SETTINGS_TYPES = {
+    "fip": "fip",
+    "behavior_curriculum": "behavior-curriculum",
+    "behavior-curriculum": "behavior-curriculum",
+}
+
+TOOL_NAMES = (
+    "list_rigs",
+    "list_projects",
+    "lookup_subject",
+    "lookup_person",
+    "get_schedule",
+    "get_acquisition",
+    "find_free_slots",
+    "list_series",
+    "get_series",
+    "list_templates",
+    "list_settings",
+    "list_runs",
+    "whoami",
+    "schedule_acquisition",
+    "move_acquisition",
+    "archive_acquisition",
+    "create_series",
+    "edit_series_from",
+    "archive_series",
+    "mark_outcome",
+)
+
+
+class Person(BaseModel):
+    person_id: str = Field(description="The person's username (see lookup_person).")
+    role: Literal["scientific_contact", "experimenter"] = "experimenter"
+
+
+def _d(text: str) -> Any:
+    return Field(description=text)
+
+
+SubjectArg = Annotated[str, _d("Subject id, e.g. '900001'.")]
+RigArg = Annotated[str, _d("A rig id (e.g. 'E2E.BEH.A') or an instrument id; see list_rigs.")]
+ProjectArg = Annotated[str, _d("Project id (its name); see list_projects.")]
+ZoneArg = Annotated[
+    str | None,
+    _d(
+        "IANA time zone for the local times, e.g. 'America/Los_Angeles'. Default: DOCKET_TIME_ZONE."
+    ),
+]
+DateArg = Annotated[str, _d("A local calendar date, e.g. '2026-03-08'.")]
+DurationArg = Annotated[int, Field(ge=1, le=1440, description="Length in elapsed minutes.")]
+DryRunArg = Annotated[
+    bool,
+    _d("True (default): only preview what would happen. False: really do it. " + NEXT_STEP),
+]
+ExpectedVersionArg = Annotated[
+    int | None,
+    _d("The expected_version from the dry-run preview. Required when dry_run=false."),
+]
+IdempotencyArg = Annotated[
+    str | None,
+    _d("The idempotency_key from the dry-run preview; a retry with it cannot repeat the change."),
+]
+PeopleArg = Annotated[list[Person] | None, _d("People on the session, with their roles.")]
+NotesArg = Annotated[str | None, _d("Operator instructions / notes shown to whoever runs it.")]
+
+
+def _warnings(items: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+    return [
+        {"code": w["code"], "message": w["message"], "session_id": w.get("acquisition_id")}
+        for w in items or []
+    ]
+
+
+def _flat_warnings(groups: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for group in groups or []:
+        for w in _warnings(group.get("warnings")):
+            out.append({"date": group.get("occurrence_local_date"), **w})
+    return out
+
+
+def _need_version(expected_version: int | None) -> int:
+    if expected_version is None:
+        raise DocketToolError(
+            "Confirming needs the expected_version from the dry-run preview: call with "
+            "dry_run=true first, show the user, then repeat with that expected_version."
+        )
+    return expected_version
+
+
+def _changed_since_preview() -> DocketToolError:
+    return DocketToolError(
+        "This changed since your preview. Preview again (dry_run=true), show the user, "
+        "and confirm that one."
+    )
+
+
+def _clashes(other: dict[str, Any], start: datetime, end: datetime) -> bool:
+    """The server's overlap rule: [start, end) against another booking; touching ends do not
+    overlap and an open-ended booking is a single point at its start."""
+    o_start = parse_instant(other["scheduled_start"])
+    if other.get("scheduled_end"):
+        return o_start < end and start < parse_instant(other["scheduled_end"])
+    return o_start < end and start <= o_start
+
+
+def _hms(value: str) -> str:
+    return parse_time(value, "start_time").strftime("%H:%M:%S")
+
+
+class DocketTools:
+    def __init__(self, api: DocketApi) -> None:
+        self.api = api
+        self._instruments: list[dict[str, Any]] | None = None
+        self._confirmed: dict[str, dict[str, Any]] = {}  # idempotency key -> result
+
+    # -- helpers ---------------------------------------------------------------------------------
+
+    def _zone(self, name: str | None) -> ZoneInfo:
+        return get_zone(name or self.api.settings.time_zone)
+
+    def _instrument_list(self, refresh: bool = False) -> list[dict[str, Any]]:
+        if self._instruments is None or refresh:
+            self._instruments = self.api.get("/api/v1/instruments", what="the instruments")
+        return self._instruments or []
+
+    def _rig_of(self, instrument_id: str) -> str | None:
+        for instrument in self._instrument_list():
+            if instrument["id"] == instrument_id:
+                return instrument["rig_id"]
+        return None
+
+    def _match_rig(self, rig: str) -> list[dict[str, Any]]:
+        wanted = rig.strip().lower()
+        for refresh in (False, True):
+            instruments = self._instrument_list(refresh)
+            by_id = [i for i in instruments if i["id"].lower() == wanted]
+            if by_id:
+                return by_id
+            by_rig = [i for i in instruments if i["rig_id"].lower() == wanted]
+            if by_rig:
+                return by_rig
+        raise DocketToolError(
+            f"Unknown rig {rig!r}. Use list_rigs to see the rigs and instruments."
+        )
+
+    def _single_instrument(self, rig: str) -> dict[str, Any]:
+        matches = self._match_rig(rig)
+        if len(matches) > 1:
+            ids = ", ".join(i["id"] for i in matches)
+            raise DocketToolError(
+                f"Rig {rig!r} has several instruments ({ids}); pass the instrument id you mean."
+            )
+        return matches[0]
+
+    def _rig_filter(self, rig: str | None) -> dict[str, Any]:
+        """Query parameters selecting a rig's (or one instrument's) acquisitions."""
+        if not rig:
+            return {}
+        matches = self._match_rig(rig)
+        if len(matches) == 1 and matches[0]["id"].lower() == rig.strip().lower():
+            return {"instrument_id": matches[0]["id"]}
+        return {"rig_id": matches[0]["rig_id"]}
+
+    def _session_view(self, s: dict[str, Any], zone: ZoneInfo) -> dict[str, Any]:
+        return {
+            "id": s["id"],
+            "status": s["effective_status"],
+            "start": describe(s["scheduled_start"], zone),
+            "end": describe(s.get("scheduled_end"), zone),
+            "subject": s["subject_id"],
+            "rig": self._rig_of(s["instrument_id"]),
+            "instrument": s["instrument_id"],
+            "project": s["project_id"],
+            "task_name": s.get("task_name"),
+            "series_id": s.get("recurring_acquisition_id"),
+            "has_runs": s["has_runs"],
+            "archived": s.get("archived_at") is not None,
+            "version": s["version"],
+        }
+
+    def _list_sessions(self, **params: Any) -> list[dict[str, Any]]:
+        return self.api.get("/api/v1/scheduled-acquisitions", what="the schedule", **params)
+
+    def _session(self, session_id: int) -> dict[str, Any]:
+        return self.api.get(f"/api/v1/scheduled-acquisitions/{session_id}", what="the session")
+
+    @staticmethod
+    def _rule_view(rule: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "frequency": rule["frequency"],
+            "weekdays": rule.get("weekdays"),
+            "interval": rule.get("interval", 1),
+            "start_date": rule["start_date"],
+            "start_time": rule["local_start_time"][:5],
+            "duration_minutes": rule["duration_minutes"],
+            "time_zone": rule["time_zone"],
+            "count": rule.get("count"),
+            "until": rule.get("until"),
+        }
+
+    def _series_view(self, d: dict[str, Any], zone: ZoneInfo) -> dict[str, Any]:
+        return {
+            "id": d["id"],
+            "subject": d["subject_id"],
+            "rig": self._rig_of(d["instrument_id"]),
+            "instrument": d["instrument_id"],
+            "project": d["project_id"],
+            "rule": self._rule_view(d["rule"]),
+            "next_start": describe(d.get("next_start"), zone),
+            "remaining": d["remaining"],
+            "ended_on": d.get("ended_on"),
+            "superseded_by": d.get("superseded_by_id"),
+            "archived": d.get("archived_at") is not None,
+            "version": d["version"],
+        }
+
+    def _nearby(self, start: datetime, end: datetime, **query: Any) -> list[dict[str, Any]]:
+        lo, hi = format_utc(start - timedelta(days=1)), format_utc(end + timedelta(days=1))
+        return [
+            o
+            for o in self._list_sessions(start=lo, end=hi, **query)
+            if o["planning_status"] != "cancelled" and not o.get("archived_at")
+        ]
+
+    def _overlaps(
+        self, start: datetime, end: datetime, *, instrument_id: str, subject: str
+    ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+        """``(warnings, advisory)`` for a new session, found by looking at the schedule.
+
+        The API has no single-session preview, so the server's rule is copied (same instrument
+        only; see ``_clashes``) for the warnings the server would return on create. Clashes of
+        the same subject on other instruments are not server warnings: they come as advisory.
+        """
+        warnings = [
+            {
+                "code": "instrument_overlap",
+                "message": f"Overlaps session {o['id']} (subject {o['subject_id']}) on {instrument_id}",
+                "session_id": o["id"],
+            }
+            for o in self._nearby(start, end, instrument_id=instrument_id)
+            if _clashes(o, start, end)
+        ]
+        advisory = [
+            {
+                "code": "subject_overlap",
+                "message": f"Subject {subject} is also on session {o['id']} ({o['instrument_id']})",
+                "session_id": o["id"],
+            }
+            for o in self._nearby(start, end, subject_id=subject)
+            if o["instrument_id"] != instrument_id and _clashes(o, start, end)
+        ]
+        return warnings, advisory
+
+    def _template_defaults(self, template_id: int | None) -> dict[str, Any]:
+        if template_id is None:
+            return {}
+        t = self.api.get(f"/api/v1/templates/{template_id}", what="the template")
+        return {
+            "operator_instructions": t.get("operator_instructions") or "",
+            "people": t.get("people") or [],
+            "type_refs": t.get("type_refs") or [],
+            "variables": t.get("variables") or [],
+        }
+
+    @staticmethod
+    def _people_body(people: list[Person] | None) -> list[dict[str, str]] | None:
+        if people is None:
+            return None
+        return [{"person_id": p.person_id, "role": p.role} for p in people]
+
+    # -- read tools ------------------------------------------------------------------------------
+
+    def list_rigs(
+        self, search: Annotated[str | None, _d("Substring of a rig or instrument id.")] = None
+    ) -> dict[str, Any]:
+        """List rigs with their instruments. Sessions are booked on a rig (its instrument)."""
+        rigs: dict[str, list[str]] = {}
+        for i in self._instrument_list(refresh=True):
+            rigs.setdefault(i["rig_id"], []).append(i["id"])
+        needle = (search or "").lower()
+        out = [
+            {"rig": rig, "instruments": ids}
+            for rig, ids in sorted(rigs.items())
+            if not needle or needle in rig.lower() or any(needle in i.lower() for i in ids)
+        ]
+        return {"count": len(out), "rigs": out}
+
+    def list_projects(
+        self, search: Annotated[str | None, _d("Substring of a project id.")] = None
+    ) -> dict[str, Any]:
+        """List project ids that sessions can be booked under."""
+        needle = (search or "").lower()
+        ids = sorted(
+            p["id"]
+            for p in self.api.get("/api/v1/projects", what="the projects")
+            if needle in p["id"].lower()
+        )
+        return {"count": len(ids), "projects": ids}
+
+    def lookup_subject(self, subject_id: SubjectArg) -> dict[str, Any]:
+        """Check that a subject exists and return its sex, date of birth and genotype."""
+        return self.api.get("/api/v1/subjects/lookup", what="the subject", subject_id=subject_id)
+
+    def lookup_person(
+        self, username: Annotated[str, _d("A person's username, e.g. 'jane.doe'.")]
+    ) -> dict[str, Any]:
+        """Check that a person exists and return their canonical username, name and email."""
+        return self.api.get("/api/v1/persons/lookup", what="the person", username=username)
+
+    def get_schedule(
+        self,
+        start_date: DateArg,
+        end_date: Annotated[str, _d("Last local date, inclusive.")],
+        rig: Annotated[str | None, _d("Only this rig or instrument.")] = None,
+        subject: Annotated[str | None, _d("Only this subject.")] = None,
+        person: Annotated[str | None, _d("Only sessions this person is on.")] = None,
+        include_archived: Annotated[bool, _d("Also list archived sessions.")] = False,
+        time_zone: ZoneArg = None,
+    ) -> dict[str, Any]:
+        """Sessions between two local dates: status, times, subject, rig, task, series and runs."""
+        zone = self._zone(time_zone)
+        lo, hi = day_bounds(
+            parse_date(start_date, "start_date"), parse_date(end_date, "end_date"), zone
+        )
+        sessions = self._list_sessions(
+            start=format_utc(lo),
+            end=format_utc(hi),
+            subject_id=subject,
+            include_archived=True if include_archived else None,
+            limit=500,
+            **self._rig_filter(rig),
+        )
+        truncated = len(sessions) >= 500
+        if person:
+            sessions = [
+                s for s in sessions if any(p["person_id"] == person for p in s.get("people", []))
+            ]
+        sessions.sort(key=lambda s: s["scheduled_start"])
+        return {
+            "time_zone": zone.key,
+            "count": len(sessions),
+            **({"truncated": True} if truncated else {}),
+            "sessions": [self._session_view(s, zone) for s in sessions],
+        }
+
+    def get_acquisition(
+        self,
+        id: Annotated[int, _d("Session (scheduled acquisition) id.")],
+        time_zone: ZoneArg = None,
+    ) -> dict[str, Any]:
+        """Full detail of one session: people, notes, variables, resolved settings and runs."""
+        zone = self._zone(time_zone)
+        s = self._session(id)
+        try:
+            settings = self.api.get(f"/api/v1/scheduled-acquisitions/{id}/resolved-settings")
+        except DocketToolError as error:
+            settings = {"unavailable": str(error)}
+        runs = self.api.get(f"/api/v1/scheduled-acquisitions/{id}/runs", what="the runs")
+        return {
+            **self._session_view(s, zone),
+            "planning_status": s["planning_status"],
+            "notes": s["operator_instructions"],
+            "people": [{"person": p["person_id"], "role": p["role"]} for p in s["people"]],
+            "settings_selection": s["type_refs"],
+            "variables": {v["key"]: v["value"] for v in s["variables"]},
+            "warnings": _warnings(s.get("warnings")),
+            "created_by": s["created_by"],
+            "resolved_settings": settings,
+            "runs": [self._run_view(r, zone) for r in runs],
+            "time_zone": zone.key,
+        }
+
+    @staticmethod
+    def _run_view(r: dict[str, Any], zone: ZoneInfo) -> dict[str, Any]:
+        # The run token identifies a run and is deliberately left out.
+        return {
+            "id": r["id"],
+            "session_id": r["scheduled_acquisition_id"],
+            "status": r["status"],
+            "origin": r["origin"],
+            "started": describe(r["started_at"], zone),
+            "ended": describe(r.get("ended_at"), zone),
+            "error": r.get("error_detail"),
+            "started_by": r["started_by"],
+        }
+
+    def find_free_slots(
+        self,
+        rig: RigArg,
+        start_date: DateArg,
+        end_date: Annotated[str, _d("Last local date, inclusive.")],
+        duration_minutes: DurationArg,
+        earliest: Annotated[str, _d("Earliest local start time each day, 24h.")] = "08:00",
+        latest: Annotated[str, _d("Latest local end time each day, 24h.")] = "18:00",
+        time_zone: ZoneArg = None,
+    ) -> dict[str, Any]:
+        """Gaps on a rig long enough for a session, computed from its schedule.
+
+        A rig with several instruments gets each instrument's gaps separately (they are
+        separate machines). Cancelled and archived sessions do not block. Deliberately unlike
+        the server's overlap warning (which treats an open-ended session as a single point), a
+        session with no end is assumed to run to the end of its local day, since its length is
+        unknown and a slot that collides with it would not be usable. A session with no end is assumed to run to
+        the end of its day. Gaps are free windows; a session can start anywhere inside one.
+        """
+        zone = self._zone(time_zone)
+        first, last = parse_date(start_date, "start_date"), parse_date(end_date, "end_date")
+        lo, hi = day_bounds(first, last, zone)
+        pad = timedelta(days=1)
+        sessions = self._list_sessions(
+            start=format_utc(lo - pad), end=format_utc(hi), limit=1000, **self._rig_filter(rig)
+        )
+        # Instruments of one rig are separate machines: each has its own calendar.
+        out: list[dict[str, Any]] = []
+        for instrument in self._match_rig(rig):
+            mine = [s for s in sessions if s["instrument_id"] == instrument["id"]]
+            try:
+                slots = free_slots(
+                    busy_intervals(mine, zone),
+                    first,
+                    last,
+                    duration_minutes,
+                    parse_time(earliest, "earliest"),
+                    parse_time(latest, "latest"),
+                    zone,
+                )
+            except ValueError as error:
+                raise DocketToolError(str(error)) from None
+            out += [
+                {
+                    "instrument": instrument["id"],
+                    "start": describe(s, zone),
+                    "end": describe(e, zone),
+                    "free_minutes": int((e - s).total_seconds() // 60),
+                }
+                for s, e in slots
+            ]
+        out.sort(key=lambda slot: (slot["start"]["utc"], slot["instrument"]))
+        notes = []
+        if len(sessions) >= 1000:
+            notes.append("The schedule was cut off at 1000 sessions: narrow the dates.")
+        if any(not x.get("scheduled_end") and not x.get("archived_at") for x in sessions):
+            notes.append("Open-ended sessions are assumed to run to the end of their day.")
+        return {
+            "rig": rig,
+            "time_zone": zone.key,
+            "needed_minutes": duration_minutes,
+            "count": len(out),
+            **({"truncated": True} if len(sessions) >= 1000 else {}),
+            **({"notes": notes} if notes else {}),
+            "slots": out,
+        }
+
+    def list_series(
+        self,
+        subject: Annotated[str | None, _d("Only this subject.")] = None,
+        rig: Annotated[str | None, _d("Only this rig or instrument.")] = None,
+        time_zone: ZoneArg = None,
+    ) -> dict[str, Any]:
+        """List recurring series (a finite pattern of sessions) and their rules."""
+        zone = self._zone(time_zone)
+        wanted = {i["id"] for i in self._match_rig(rig)} if rig else None
+        items = self.api.get(
+            "/api/v1/recurring-acquisitions", what="the series", subject_id=subject, limit=200
+        )
+        views = [
+            self._series_view(d, zone)
+            for d in items
+            if wanted is None or d["instrument_id"] in wanted
+        ]
+        return {"time_zone": zone.key, "count": len(views), "series": views}
+
+    def get_series(
+        self, id: Annotated[int, _d("Series id.")], time_zone: ZoneArg = None
+    ) -> dict[str, Any]:
+        """One series: its rule, how many sessions it made and which dates are exceptions."""
+        zone = self._zone(time_zone)
+        d = self.api.get(f"/api/v1/recurring-acquisitions/{id}", what="the series")
+        occ = d["occurrences"]
+        return {
+            **self._series_view(d["definition"], zone),
+            "sessions": {
+                "count": occ["count"],
+                "first": describe(occ.get("first_scheduled_start"), zone),
+                "last": describe(occ.get("last_scheduled_start"), zone),
+                "ids": occ["ids"],
+            },
+            "exceptions": d["exceptions"],
+            "notes": d["definition"]["operator_instructions"],
+        }
+
+    def list_templates(self) -> dict[str, Any]:
+        """List scheduling templates (named defaults: people, notes, settings, duration)."""
+        items = self.api.get("/api/v1/templates", what="the templates")
+        return {
+            "count": len(items),
+            "templates": [
+                {
+                    "id": t["id"],
+                    "name": t["name"],
+                    "subject": t.get("subject_id"),
+                    "rig": t.get("instrument_id"),
+                    "project": t.get("project_id"),
+                    "duration_minutes": t.get("duration_minutes"),
+                    "start_time": (t.get("local_start_time") or "")[:5] or None,
+                    "people": [{"person": p["person_id"], "role": p["role"]} for p in t["people"]],
+                    "notes": t.get("operator_instructions"),
+                }
+                for t in items
+            ],
+        }
+
+    def list_settings(
+        self,
+        acquisition_type: Annotated[str, _d("'fip' or 'behavior_curriculum'.")],
+        subject: Annotated[str | None, _d("Only this subject.")] = None,
+        live_only: Annotated[bool, _d("Only the settings versions currently in force.")] = False,
+        limit: Annotated[int, Field(ge=1, le=200, description="Most versions to return.")] = 20,
+    ) -> Any:
+        """List stored settings versions for an acquisition type."""
+        slug = SETTINGS_TYPES.get(acquisition_type.strip().lower())
+        if slug is None:
+            raise DocketToolError(
+                f"Unknown acquisition type {acquisition_type!r}; use 'fip' or 'behavior_curriculum'."
+            )
+        suffix = "/live" if live_only else ""
+        return self.api.get(
+            f"/api/v1/settings/{slug}{suffix}", what="the settings", subject_id=subject, limit=limit
+        )
+
+    def list_runs(
+        self,
+        acquisition_id: Annotated[int | None, _d("Runs of this session.")] = None,
+        subject: Annotated[str | None, _d("Runs of this subject's sessions.")] = None,
+        rig: Annotated[str | None, _d("Runs on this rig or instrument.")] = None,
+        start_date: Annotated[
+            str | None, _d("Only runs started on or after this local date.")
+        ] = None,
+        end_date: Annotated[
+            str | None, _d("Only runs started on or before this local date.")
+        ] = None,
+        time_zone: ZoneArg = None,
+    ) -> dict[str, Any]:
+        """List runs (an attempt to execute a session) by session, subject or rig, newest first."""
+        zone = self._zone(time_zone)
+        truncated = False
+        if acquisition_id is not None:
+            runs = self.api.get(
+                f"/api/v1/scheduled-acquisitions/{acquisition_id}/runs", what="the runs"
+            )
+        elif subject or rig:
+            sessions = self._list_sessions(subject_id=subject, limit=200, **self._rig_filter(rig))
+            runs = []
+            with_runs = [s for s in sessions if s["has_runs"]]
+            truncated = len(sessions) >= 200 or len(with_runs) > 50
+            for s in with_runs[:50]:
+                runs += self.api.get(
+                    f"/api/v1/scheduled-acquisitions/{s['id']}/runs", what="the runs"
+                )
+        else:
+            runs = self.api.get("/api/v1/runs", what="the runs", limit=200)
+            truncated = len(runs) >= 200
+        if start_date or end_date:
+            lo = (
+                day_bounds(
+                    parse_date(start_date or end_date or "", "start_date"),
+                    parse_date(start_date or end_date or "", "start_date"),
+                    zone,
+                )[0]
+                if start_date
+                else None
+            )
+            hi = (
+                day_bounds(
+                    parse_date(end_date or start_date or "", "end_date"),
+                    parse_date(end_date or start_date or "", "end_date"),
+                    zone,
+                )[1]
+                if end_date
+                else None
+            )
+            runs = [
+                r
+                for r in runs
+                if (lo is None or parse_instant(r["started_at"]) >= lo)
+                and (hi is None or parse_instant(r["started_at"]) < hi)
+            ]
+        runs.sort(key=lambda r: r["started_at"], reverse=True)
+        return {
+            "time_zone": zone.key,
+            "count": len(runs),
+            **({"truncated": True} if truncated else {}),
+            "runs": [self._run_view(r, zone) for r in runs],
+        }
+
+    def whoami(self) -> dict[str, Any]:
+        """The server's auth mode and who you are to it: caller, roles (and their source), grants.
+
+        Shows you as yourself when a credential is available without interaction (an API token,
+        client credentials or a cached sign-in); otherwise as anonymous. It never starts a sign-in.
+        """
+        me, signed_in = self.api.me_as_caller()
+        return {
+            **me,
+            "signed_in": signed_in,
+            "api_url": self.api.settings.api_url,
+            "time_zone": self.api.settings.time_zone,
+        }
+
+    # -- write tools -----------------------------------------------------------------------------
+
+    def schedule_acquisition(
+        self,
+        subject: SubjectArg,
+        rig: RigArg,
+        project: ProjectArg,
+        start: Annotated[str, _d("Local start, e.g. '2026-03-08T09:30' (no offset).")],
+        duration_minutes: DurationArg,
+        people: PeopleArg = None,
+        notes: NotesArg = None,
+        template_id: Annotated[int | None, _d("Start from this template's defaults.")] = None,
+        time_zone: ZoneArg = None,
+        dry_run: DryRunArg = True,
+        idempotency_key: IdempotencyArg = None,
+    ) -> dict[str, Any]:
+        """Schedule one acquisition session. Call with dry_run=true first and show the user the preview.
+
+        The preview checks the subject, project and people exist and looks for overlaps on the
+        rig (the API has no preview for a single session, so this is estimated here with the
+        server's rule; the server checks again when it creates it). Confirm with dry_run=false
+        and the preview's idempotency_key: repeating the call cannot book it twice.
+        """
+        zone = self._zone(time_zone)
+        parsed = parse_local_datetime(start, zone)
+        end = parsed.utc + timedelta(minutes=duration_minutes)
+        instrument = self._single_instrument(rig)
+        defaults = self._template_defaults(template_id)
+        body: dict[str, Any] = {
+            "subject_id": subject,
+            "instrument_id": instrument["id"],
+            "project_id": project,
+            "scheduled_start": format_utc(parsed.utc),
+            "scheduled_end": format_utc(end),
+            "operator_instructions": notes
+            if notes is not None
+            else defaults.get("operator_instructions", ""),
+            "people": self._people_body(people)
+            if people is not None
+            else defaults.get("people", []),
+            "type_refs": defaults.get("type_refs", []),
+            "variables": defaults.get("variables", []),
+        }
+        summary = {
+            "subject": subject,
+            "rig": instrument["rig_id"],
+            "instrument": instrument["id"],
+            "project": project,
+            "start": describe(parsed.utc, zone),
+            "end": describe(end, zone),
+            "duration_minutes": duration_minutes,
+            "people": [{"person": p["person_id"], "role": p["role"]} for p in body["people"]],
+            "notes": body["operator_instructions"],
+            "time_zone": zone.key,
+        }
+        extra = (
+            ["That local time happens twice (clocks go back): the first occurrence was used."]
+            if parsed.ambiguous
+            else []
+        )
+        if dry_run:
+            key = str(uuid.uuid4())
+            warnings, advisory = self._overlaps(
+                parsed.utc, end, instrument_id=instrument["id"], subject=subject
+            )
+            return {
+                "dry_run": True,
+                "would_create": summary,
+                "warnings": warnings,
+                "advisory": advisory,
+                "warnings_note": "estimated here; the server re-checks on create",
+                "problems": self._problems(body),
+                "notes": extra,
+                "idempotency_key": key,
+                "confirm_with": {"dry_run": False, "idempotency_key": key},
+                "next_step": NEXT_STEP,
+            }
+        key = idempotency_key or str(uuid.uuid4())
+        if key in self._confirmed:  # the model retried this confirmation
+            return {**self._confirmed[key], "replayed": True}
+        # The create endpoint takes no idempotency key, so a retry after a timeout is caught by
+        # looking for the identical session that an earlier attempt may have made.
+        for other in self._nearby(parsed.utc, end, instrument_id=instrument["id"]):
+            if (
+                other["subject_id"] == subject
+                and other["scheduled_start"] == body["scheduled_start"]
+                and other["scheduled_end"] == body["scheduled_end"]
+                and other["project_id"] == project
+            ):
+                return {
+                    "dry_run": False,
+                    "already_exists": self._session_view(other, zone),
+                    "note": "An identical session already exists, so nothing was created.",
+                }
+        created = self.api.post(
+            "/api/v1/scheduled-acquisitions", body, action="schedule an acquisition"
+        )
+        result = {
+            "dry_run": False,
+            "created": self._session_view(created, zone),
+            "warnings": _warnings(created.get("warnings")),
+            "notes": extra,
+        }
+        self._confirmed[key] = result
+        return result
+
+    def _problems(self, body: dict[str, Any]) -> list[str]:
+        """Things that would make creation fail: unknown subject, project or person."""
+        problems: list[str] = []
+        subject = self.api.get("/api/v1/subjects/lookup", subject_id=body["subject_id"])
+        if not subject.get("valid"):
+            problems.append(
+                f"Subject {body['subject_id']!r}: {subject.get('detail') or 'not found'}"
+            )
+        projects = {p["id"] for p in self.api.get("/api/v1/projects")}
+        if body["project_id"] not in projects:
+            problems.append(f"Unknown project {body['project_id']!r} (see list_projects).")
+        for person in body["people"]:
+            looked = self.api.get("/api/v1/persons/lookup", username=person["person_id"])
+            if not looked.get("valid"):
+                problems.append(
+                    f"Person {person['person_id']!r}: {looked.get('detail') or 'not found'}"
+                )
+        return problems
+
+    def move_acquisition(
+        self,
+        id: Annotated[int, _d("Session id (see get_schedule).")],
+        start: Annotated[str | None, _d("New local start, e.g. '2026-03-08T09:30'.")] = None,
+        duration_minutes: Annotated[
+            int | None, Field(ge=1, le=1440, description="New length in minutes.")
+        ] = None,
+        rig: Annotated[str | None, _d("Move to this rig or instrument.")] = None,
+        time_zone: ZoneArg = None,
+        dry_run: DryRunArg = True,
+        expected_version: ExpectedVersionArg = None,
+    ) -> dict[str, Any]:
+        """Change a session's start, length or rig. Call with dry_run=true first and show the user the preview.
+
+        Confirm with dry_run=false and the preview's expected_version: if the session changed
+        since the preview the call is refused and you must preview again.
+        """
+        zone = self._zone(time_zone)
+        if start is None and duration_minutes is None and rig is None:
+            raise DocketToolError("Nothing to change: give start, duration_minutes or rig.")
+        if not dry_run:
+            _need_version(expected_version)
+        current = self._session(id)
+        if not dry_run and current["version"] != expected_version:
+            raise _changed_since_preview()
+        cur_start = parse_instant(current["scheduled_start"])
+        cur_end = parse_instant(current["scheduled_end"]) if current.get("scheduled_end") else None
+        body: dict[str, Any] = {"expected_version": current["version"]}
+        extra: list[str] = []
+        new_start = cur_start
+        if start is not None:
+            parsed = parse_local_datetime(start, zone)
+            new_start = parsed.utc
+            body["scheduled_start"] = format_utc(new_start)
+            if parsed.ambiguous:
+                extra.append(
+                    "That local time happens twice (clocks go back): the first occurrence was used."
+                )
+        if duration_minutes is not None:
+            body["scheduled_end"] = format_utc(new_start + timedelta(minutes=duration_minutes))
+        elif start is not None and cur_end is not None:
+            body["scheduled_end"] = format_utc(new_start + (cur_end - cur_start))
+        if rig is not None:
+            body["instrument_id"] = self._single_instrument(rig)["id"]
+        path = f"/api/v1/scheduled-acquisitions/{id}"
+        if dry_run:
+            preview = self.api.preview(f"{path}/edit-preview", body)
+            return {
+                "dry_run": True,
+                "session_id": id,
+                "before": self._session_view(current, zone),
+                "after": {
+                    "start": describe(preview["scheduled_start"], zone),
+                    "end": describe(preview.get("scheduled_end"), zone),
+                    "instrument": preview["instrument_id"],
+                    "rig": self._rig_of(preview["instrument_id"]),
+                },
+                "part_of_series": preview.get("recurring_acquisition_id"),
+                "warnings": _warnings(preview.get("warnings")),
+                "notes": extra,
+                "expected_version": current["version"],
+                "confirm_with": {"dry_run": False, "expected_version": current["version"]},
+                "next_step": NEXT_STEP,
+            }
+        updated = self.api.patch(path, body, action="move this session")
+        return {
+            "dry_run": False,
+            "moved": self._session_view(updated, zone),
+            "warnings": _warnings(updated.get("warnings")),
+            "notes": extra,
+        }
+
+    def archive_acquisition(
+        self,
+        id: Annotated[int, _d("Session id (see get_schedule).")],
+        time_zone: ZoneArg = None,
+        dry_run: DryRunArg = True,
+        expected_version: ExpectedVersionArg = None,
+    ) -> dict[str, Any]:
+        """Archive (cancel and hide) a session; nothing is ever hard-deleted. Call with dry_run=true first and show the user the preview.
+
+        Confirm with dry_run=false and the preview's expected_version.
+        """
+        zone = self._zone(time_zone)
+        if not dry_run:
+            version = _need_version(expected_version)
+            archived = self.api.post(
+                f"/api/v1/scheduled-acquisitions/{id}/archive",
+                {"expected_version": version},
+                action="archive this session",
+            )
+            return {"dry_run": False, "archived": self._session_view(archived, zone)}
+        current = self._session(id)
+        view = self._session_view(current, zone)
+        return {
+            "dry_run": True,
+            "would_archive": view,
+            "already_archived": view["archived"],
+            "part_of_series": current.get("recurring_acquisition_id"),
+            "expected_version": current["version"],
+            "confirm_with": {"dry_run": False, "expected_version": current["version"]},
+            "next_step": NEXT_STEP,
+        }
+
+    def mark_outcome(
+        self,
+        acquisition_id: Annotated[int, _d("Session id.")],
+        outcome: Annotated[
+            Literal["succeeded", "failed", "cancelled"], _d("How the session ended up.")
+        ],
+        time_zone: ZoneArg = None,
+        dry_run: DryRunArg = True,
+        expected_version: ExpectedVersionArg = None,
+    ) -> dict[str, Any]:
+        """Record a session's outcome by hand (succeeded, failed or cancelled). Call with dry_run=true first and show the user the preview.
+
+        Confirm with dry_run=false and the preview's expected_version.
+        """
+        zone = self._zone(time_zone)
+        if not dry_run:
+            version = _need_version(expected_version)
+            updated = self.api.post(
+                f"/api/v1/scheduled-acquisitions/{acquisition_id}/planning-status",
+                {"planning_status": outcome, "expected_version": version},
+                action="set this session's outcome",
+            )
+            return {"dry_run": False, "session": self._session_view(updated, zone)}
+        current = self._session(acquisition_id)
+        return {
+            "dry_run": True,
+            "session": self._session_view(current, zone),
+            "would_set": outcome,
+            "currently": current["planning_status"],
+            "expected_version": current["version"],
+            "confirm_with": {"dry_run": False, "expected_version": current["version"]},
+            "next_step": NEXT_STEP,
+        }
+
+    # -- series ----------------------------------------------------------------------------------
+
+    @staticmethod
+    def _end_rule(count: int | None, until: str | None) -> dict[str, Any]:
+        if (count is None) == (until is None):
+            raise DocketToolError(
+                "Give exactly one of count or until: a series is never open-ended."
+            )
+        return {"count": count, "until": parse_date(until, "until").isoformat() if until else None}
+
+    def _preview_view(
+        self, preview: dict[str, Any], zone: ZoneInfo, limit: int = 31
+    ) -> dict[str, Any]:
+        occ = preview["occurrences"]
+        return {
+            "session_count": len(occ),
+            "sessions": [
+                {
+                    "date": o["occurrence_local_date"],
+                    "start": describe(o["scheduled_start"], zone),
+                    "end": describe(o["scheduled_end"], zone),
+                }
+                for o in occ[:limit]
+            ],
+            "sessions_not_listed": max(0, len(occ) - limit),
+            "warnings": [
+                {"date": o["occurrence_local_date"], **w}
+                for o in occ
+                for w in _warnings(o.get("warnings"))
+            ],
+            "skipped_dates": [
+                {"date": s["occurrence_local_date"], "reason": s["reason"], "message": s["message"]}
+                for s in preview.get("skipped", [])
+            ],
+        }
+
+    def create_series(
+        self,
+        subject: SubjectArg,
+        rig: RigArg,
+        project: ProjectArg,
+        frequency: Annotated[Literal["daily", "weekly"], _d("daily or weekly.")],
+        start_date: Annotated[str, _d("First local date a session may fall on.")],
+        start_time: Annotated[str, _d("Local start time of each session, e.g. '09:30'.")],
+        duration_minutes: DurationArg,
+        weekdays: Annotated[list[Weekday] | None, _d("Weekly only: the days of the week.")] = None,
+        interval: Annotated[int, Field(ge=1, description="Every n days or weeks.")] = 1,
+        count: Annotated[int | None, Field(ge=1, le=366, description="Number of sessions.")] = None,
+        until: Annotated[str | None, _d("Last local date, inclusive (within six months).")] = None,
+        time_zone: ZoneArg = None,
+        source_acquisition_id: Annotated[
+            int | None, _d("Copy settings and people from this session.")
+        ] = None,
+        people: PeopleArg = None,
+        notes: NotesArg = None,
+        dry_run: DryRunArg = True,
+        idempotency_key: IdempotencyArg = None,
+    ) -> dict[str, Any]:
+        """Create a finite recurring series of sessions. Call with dry_run=true first and show the user the preview.
+
+        Sessions that fall in a daylight-saving gap are skipped and listed. Confirm with
+        dry_run=false and the preview's idempotency_key: repeating the call cannot create it twice.
+        """
+        zone = self._zone(time_zone)
+        if frequency == "weekly" and not weekdays:
+            raise DocketToolError("A weekly series needs weekdays, e.g. ['monday', 'thursday'].")
+        rule = {
+            "frequency": frequency,
+            "local_start_time": _hms(start_time),
+            "duration_minutes": duration_minutes,
+            "time_zone": zone.key,
+            "start_date": parse_date(start_date, "start_date").isoformat(),
+            "interval": interval,
+            "weekdays": weekdays if frequency == "weekly" else None,
+            **self._end_rule(count, until),
+        }
+        body: dict[str, Any] = {
+            "subject_id": subject,
+            "instrument_id": self._single_instrument(rig)["id"],
+            "project_id": project,
+            "rule": rule,
+            "operator_instructions": notes or "",
+            "people": self._people_body(people),
+            "source_acquisition_id": source_acquisition_id,
+        }
+        body = {k: v for k, v in body.items() if v is not None}
+        if dry_run:
+            key = str(uuid.uuid4())
+            preview = self.api.preview("/api/v1/recurring-acquisitions/preview", body)
+            return {
+                "dry_run": True,
+                "series": self._rule_view(rule),
+                **self._preview_view(preview, zone),
+                "idempotency_key": key,
+                "confirm_with": {"dry_run": False, "idempotency_key": key},
+                "next_step": NEXT_STEP,
+            }
+        created = self.api.post(
+            "/api/v1/recurring-acquisitions",
+            body,
+            action="create a series",
+            idempotency_key=idempotency_key or str(uuid.uuid4()),
+        )
+        return {
+            "dry_run": False,
+            "series": self._series_view(created["definition"], zone),
+            "session_ids": created["occurrence_ids"],
+            "skipped_dates": created["skipped"],
+            "warnings": _flat_warnings(created.get("warnings")),
+        }
+
+    def edit_series_from(
+        self,
+        series_id: Annotated[int, _d("Series id (see list_series).")],
+        effective_date: Annotated[str, _d("The change applies from this local date on.")],
+        rig: Annotated[str | None, _d("New rig or instrument.")] = None,
+        project: Annotated[str | None, _d("New project.")] = None,
+        frequency: Annotated[Literal["daily", "weekly"] | None, _d("New frequency.")] = None,
+        weekdays: Annotated[list[Weekday] | None, _d("New weekdays (weekly).")] = None,
+        interval: Annotated[int | None, Field(ge=1, description="New every-n.")] = None,
+        start_time: Annotated[str | None, _d("New local start time, e.g. '10:00'.")] = None,
+        duration_minutes: Annotated[
+            int | None, Field(ge=1, le=1440, description="New length.")
+        ] = None,
+        count: Annotated[
+            int | None, Field(ge=1, le=366, description="New number of sessions from the date on.")
+        ] = None,
+        until: Annotated[str | None, _d("New last local date, inclusive.")] = None,
+        time_zone: Annotated[str | None, _d("New IANA zone for the series.")] = None,
+        notes: NotesArg = None,
+        people: PeopleArg = None,
+        dry_run: DryRunArg = True,
+        expected_version: ExpectedVersionArg = None,
+        idempotency_key: IdempotencyArg = None,
+    ) -> dict[str, Any]:
+        """Change a series from a date on: the old series ends the day before and a new one takes over.
+
+        Sessions that already have runs, or were edited by hand, are kept as they are. Call with
+        dry_run=true first and show the user the preview. Unchanged fields, and the end of the
+        series when neither count nor until is given, carry over. Confirm with dry_run=false, the
+        same arguments, and the preview's expected_version and idempotency_key: if the series
+        changed since the preview the call is refused and you must preview again.
+        """
+        if not dry_run:
+            _need_version(expected_version)
+        zone = self._zone(time_zone)
+        detail = self.api.get(f"/api/v1/recurring-acquisitions/{series_id}", what="the series")
+        d = detail["definition"]
+        if not dry_run and d["version"] != expected_version:
+            raise _changed_since_preview()
+        rule = dict(d["rule"])
+        if time_zone:
+            rule["time_zone"] = zone.key
+        series_zone = get_zone(rule["time_zone"])
+        if frequency:
+            rule["frequency"] = frequency
+        if weekdays is not None:
+            rule["weekdays"] = weekdays
+        if rule["frequency"] == "daily":
+            rule["weekdays"] = None
+        elif not rule.get("weekdays"):
+            raise DocketToolError("A weekly series needs weekdays, e.g. ['monday', 'thursday'].")
+        if interval:
+            rule["interval"] = interval
+        if start_time:
+            rule["local_start_time"] = _hms(start_time)
+        if duration_minutes:
+            rule["duration_minutes"] = duration_minutes
+        rule["start_date"] = parse_date(effective_date, "effective_date").isoformat()
+        if count is not None or until is not None:
+            rule.update(self._end_rule(count, until))
+        else:
+            last = detail["occurrences"].get("last_scheduled_start")
+            keep = (
+                parse_instant(last).astimezone(series_zone).date().isoformat()
+                if last
+                else rule.get("until")
+            )
+            rule.update({"count": None, "until": keep})
+        body: dict[str, Any] = {
+            "expected_version": d["version"],
+            "effective_date": rule["start_date"],
+            "subject_id": d["subject_id"],
+            "instrument_id": self._single_instrument(rig)["id"] if rig else d["instrument_id"],
+            "project_id": project or d["project_id"],
+            "rule": rule,
+            "operator_instructions": notes if notes is not None else d["operator_instructions"],
+            "people": self._people_body(people) if people is not None else d["people"],
+            "type_refs": d["type_refs"],
+            "variables": d["variables"],
+        }
+        path = f"/api/v1/recurring-acquisitions/{series_id}/split"
+        if dry_run:
+            key = str(uuid.uuid4())
+            preview = self.api.preview(f"{path}/preview", body)
+            return {
+                "dry_run": True,
+                "from_date": rule["start_date"],
+                "new_series": self._rule_view(rule),
+                **self._preview_view(preview, series_zone),
+                "replaced_session_ids": preview["replaced"],
+                "kept_sessions": preview["kept"],
+                "expected_version": d["version"],
+                "idempotency_key": key,
+                "confirm_with": {
+                    "dry_run": False,
+                    "expected_version": d["version"],
+                    "idempotency_key": key,
+                },
+                "next_step": NEXT_STEP,
+            }
+        done = self.api.post(
+            path,
+            body,
+            action="edit this series",
+            idempotency_key=idempotency_key or str(uuid.uuid4()),
+        )
+        return {
+            "dry_run": False,
+            "new_series": self._series_view(done["definition"], series_zone),
+            "previous_series": self._series_view(done["previous"], series_zone),
+            "new_session_ids": done["occurrence_ids"],
+            "replaced_session_ids": done["replaced"],
+            "kept_sessions": done["kept"],
+            "skipped_dates": done["skipped"],
+            "warnings": _flat_warnings(done.get("warnings")),
+        }
+
+    def archive_series(
+        self,
+        id: Annotated[int, _d("Series id.")],
+        future_sessions: Annotated[
+            Literal["keep", "archive"],
+            _d("What happens to its sessions that have not happened yet."),
+        ],
+        time_zone: ZoneArg = None,
+        dry_run: DryRunArg = True,
+        expected_version: ExpectedVersionArg = None,
+    ) -> dict[str, Any]:
+        """Archive a series, and either keep or archive its upcoming sessions. Call with dry_run=true first and show the user the preview.
+
+        Confirm with dry_run=false and the preview's expected_version.
+        """
+        zone = self._zone(time_zone)
+        if not dry_run:
+            version = _need_version(expected_version)
+            done = self.api.post(
+                f"/api/v1/recurring-acquisitions/{id}/archive",
+                {"expected_version": version, "future_occurrences": future_sessions},
+                action="archive this series",
+            )
+            return {
+                "dry_run": False,
+                "series": self._series_view(done["definition"], zone),
+                "archived_session_ids": done["archived_occurrence_ids"],
+            }
+        detail = self.api.get(f"/api/v1/recurring-acquisitions/{id}", what="the series")
+        d = detail["definition"]
+        now = datetime.now(UTC)
+        # Sessions kept from an earlier series are attached to this one but carry the old series
+        # id, so also match the definition's own occurrence ids (same subject and instrument).
+        own_ids = set(detail["occurrences"]["ids"])
+        upcoming = [
+            s
+            for s in self._list_sessions(
+                subject_id=d["subject_id"],
+                instrument_id=d["instrument_id"],
+                start=format_utc(now),
+                limit=500,
+            )
+            if (s["id"] in own_ids or s.get("recurring_acquisition_id") == id)
+            and parse_instant(s["scheduled_start"]) > now
+        ]
+        affected = (
+            [s for s in upcoming if not s["has_runs"]] if future_sessions == "archive" else []
+        )
+        return {
+            "dry_run": True,
+            "series": self._series_view(d, zone),
+            "future_sessions": future_sessions,
+            "upcoming_sessions": len(upcoming),
+            "would_archive_sessions": [self._session_view(s, zone) for s in affected],
+            "note": "Estimated from the schedule; the server decides which sessions are untouched.",
+            "expected_version": d["version"],
+            "confirm_with": {"dry_run": False, "expected_version": d["version"]},
+            "next_step": NEXT_STEP,
+        }